oharkins/weatherxm-mcp-server

WeatherXM Pro MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to real-time weather data from the WeatherXM decentralized weather network worldwide.

Features

• Real-time Weather Data: Get current weather conditions from any WeatherXM station
• Weather Forecasting: Access hourly and daily weather forecasts
• Historical Data: Retrieve historical weather data for trend analysis
• Weather Alerts: Get active weather alerts and warnings
• Station Discovery: Find weather stations near any location
• Advanced Search: Search for stations by name or location
• Weather Cells: Explore the decentralized weather network coverage
• Data Quality Assessment: Check the reliability of weather data from specific stations
• Comprehensive Weather Metrics: Temperature, humidity, wind, pressure, UV index, solar irradiance, and precipitation data
• Global Coverage: Access weather data from WeatherXM stations around the world

Prerequisites

• Node.js 18 or higher
• A WeatherXM Pro API key (get one at pro.weatherxm.com)

Configuration

The server requires a WeatherXM Pro API key to function. You'll need to provide this when connecting to the server.

Getting a WeatherXM Pro API Key

1. Visit pro.weatherxm.com
2. Sign up for a Pro account
3. Navigate to the API section
4. Generate an API key

Quick Fix for "Connection Failed" / "Load Failed"

The most common cause of connection failures is a missing or invalid WeatherXM Pro API key. Follow these steps:

1. Test Your API Key

Run this command to test your API key:

# Set your API key
export WEATHERXM_API_KEY="your_api_key_here"

# Test the connection
node test-api.js

2. Configure Your MCP Client

Option A: Environment Variable (Recommended)

export WEATHERXM_API_KEY="your_api_key_here"

Option B: MCP Client Configuration

For Claude Desktop or other MCP clients, add to your configuration:

{
  "mcpServers": {
    "weatherxm": {
      "command": "npx",
      "args": ["@oharkins/weatherxm-mcp-server"],
      "env": {
        "WEATHERXM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option C: Direct Server Configuration

If running the server directly:

WEATHERXM_API_KEY="your_api_key_here" npm run dev

MCP Client Configuration Examples

Using the Published NPM Package

For most users, the recommended approach is to use the published npm package:

{
  "mcpServers": {
    "weatherxm": {
      "command": "npx",
      "args": ["@oharkins/weatherxm-mcp-server"],
      "env": {
        "WEATHERXM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Using Local Development Version

For developers or users who want to run the latest development version:

{
  "mcpServers": {
    "weatherxm": {
      "command": "node",
      "args": ["/path/to/weatherxm-mcp-server/dist/index.js"],
      "env": {
        "WEATHERXM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note: Replace /path/to/weatherxm-mcp-server with the actual path to your cloned repository. Make sure to run npm run build:tsc first to generate the dist/index.js file using the traditional TypeScript compiler.

Using Local Development with TypeScript

For active development with hot reloading:

{
  "mcpServers": {
    "weatherxm": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "/path/to/weatherxm-mcp-server",
      "env": {
        "WEATHERXM_API_KEY": "your_api_key_here"
      }
    }
  }
}

Note: This requires the development dependencies to be installed (npm install) and is only recommended for development purposes.

3. Verify the Connection

After configuration, the server should start successfully and you should be able to use weather tools like:

• "What's the weather like at station WXM123456?"
• "Find weather stations near New York City"
• "Get weather alerts for 40.7128, -74.0060"

Installation

1. Clone this repository:

git clone <repository-url>
cd weatherxm-mcp-server

2. Install dependencies:

npm install

3. Build the server:

Option A: Using Smithery (Default)

npm run build

Option B: Using Traditional TypeScript

npm run build:tsc

Note: The traditional TypeScript build creates a dist/ directory with compiled JavaScript files. Use this option if you prefer not to use Smithery or need the compiled output for deployment.

Development and Local Runner

This server supports both Smithery and local runner capabilities for development and testing.

Using Smithery (Recommended)

Smithery provides a modern development experience with hot reloading and optimized builds.

Development mode:

npm run dev

Build for production:

npm run build

Using Local Runner

For local development and testing without Smithery:

Set your API key:

export WEATHERXM_API_KEY="your_api_key_here"

Run the local runner:

npm run runner

Or run directly with tsx:

tsx src/runner.ts

Development Scripts

• npm run dev - Start Smithery development server
• npm run dev:tsc - Start development with TypeScript compiler
• npm run runner - Run local server for testing
• npm run build - Build with Smithery
• npm run build:tsc - Build with TypeScript compiler
• npm run clean - Clean build artifacts
• npm start - Run built server
• npm run start:dev - Run development server
• npm test - Test server creation

Configuration Files

The repository includes example configuration files for MCP clients:

• mcp-config-example.json - Standard configuration using the published npm package
• mcp-config-local-dev.json - Local development configuration

Copy and modify these files as needed for your MCP client setup.

Available Tools

1. Get Current Weather (get_current_weather)

Retrieves the latest weather observation from a specific WeatherXM station.

Parameters:

• station_id (string): WeatherXM station ID (e.g., "station_123" or "WXM123456")

Returns:

• Temperature (Fahrenheit and Celsius)
• Feels like temperature
• Weather conditions
• Humidity percentage
• Dew point
• Wind speed and direction
• Wind gust (if available)
• Barometric pressure
• UV index
• Solar irradiance
• Precipitation rate and accumulated precipitation
• Data quality score

2. Get Hourly Forecast (get_hourly_forecast)

Retrieves detailed hourly weather forecasts for a specific WeatherXM station.

Parameters:

• station_id (string): WeatherXM station ID
• hours (number, optional): Number of hours to forecast (1-48, default: 48)

Returns:

• Hourly temperature predictions
• Precipitation probability
• Wind conditions
• Humidity and pressure forecasts
• UV index predictions

3. Get Daily Forecast (get_daily_forecast)

Retrieves daily weather forecasts including high/low temperatures and precipitation.

Parameters:

• station_id (string): WeatherXM station ID
• days (number, optional): Number of days to forecast (1-7, default: 7)

Returns:

• Daily high and low temperatures
• Precipitation probability and type
• Wind conditions
• Humidity and pressure forecasts
• UV index predictions

4. Get Historical Weather Data (get_historical_weather)

Retrieves historical weather data for trend analysis and pattern recognition.

Parameters:

• station_id (string): WeatherXM station ID
• start_date (string): Start date in ISO format (YYYY-MM-DD)
• end_date (string): End date in ISO format (YYYY-MM-DD)

Returns:

• Historical temperature data
• Precipitation records
• Wind and pressure history
• Summary statistics
• Recent observations

5. Get Weather Alerts (get_weather_alerts)

Retrieves active weather alerts and warnings for a specific location.

Parameters:

• latitude (number): Latitude in decimal degrees
• longitude (number): Longitude in decimal degrees

Returns:

• Active weather alerts
• Alert severity and type
• Effective and expiration times
• Affected areas
• Alert descriptions

6. Find Weather Stations (find_weather_stations)

Discovers WeatherXM stations near a specified location.

Parameters:

• latitude (number): Latitude in decimal degrees
• longitude (number): Longitude in decimal degrees
• radius (number, optional): Search radius in kilometers (default: 50, max: 100)

Returns:

• List of nearby stations with their details
• Station names, IDs, and locations
• Station creation dates
• Cell index information

7. Search Weather Stations (search_weather_stations)

Searches for WeatherXM stations by name or location description.

Parameters:

• query (string): Search query (station name, city, or location)
• page (number, optional): Page number for pagination (default: 1)
• limit (number, optional): Results per page (1-50, default: 10)

Returns:

• Matching stations with details
• Total result count
• Pagination information

8. Get Weather Cells (get_weather_cells)

Retrieves WeatherXM weather cells (geographic areas) near a location.

Parameters:

• latitude (number): Latitude in decimal degrees
• longitude (number): Longitude in decimal degrees
• radius (number, optional): Search radius in kilometers (default: 50, max: 100)

Returns:

• Weather cell information
• Cell center coordinates
• Station count per cell
• Network coverage details

9. Get Station Health (get_station_health)

Assesses the data quality and reliability of a specific WeatherXM station.

Parameters:

• station_id (string): WeatherXM station ID

Returns:

• Data quality score (0-100%)
• Location quality score and reason
• Overall assessment of data reliability
• Health check timestamp

10. Get Station Local Time (get_station_local_time)

Gets the current local time at a station's location.

Parameters:

• station_id (string): WeatherXM station ID

Returns:

• Current local time at the station's location

Usage Examples

Example 1: Get Current Weather

What's the weather like at station WXM123456?

Example 2: Get Weather Forecast

What's the hourly forecast for station WXM789012 for the next 24 hours?

Example 3: Get Historical Data

Show me the weather data for station WXM345678 from January 1st to January 7th, 2024

Example 4: Check Weather Alerts

Are there any weather alerts for New York City (40.7128, -74.0060)?

Example 5: Find Stations Near a Location

Find weather stations within 25km of New York City (40.7128, -74.0060)

Example 6: Search for Stations

Search for weather stations in "San Francisco"

Example 7: Check Station Data Quality

How reliable is the weather data from station station_789?

Example 8: Get Local Time

What time is it at station WXM456789?

Data Units

The server provides weather data in the following units:

• Temperature: Celsius (with Fahrenheit conversion)
• Wind Speed: m/s (with mph conversion)
• Pressure: hPa (with inHg conversion)
• Precipitation: mm (with inches conversion)
• Solar Irradiance: W/m²
• UV Index: dimensionless
• Humidity: percentage

Error Handling

The server handles various error conditions:

• 401 Unauthorized: Invalid API key
• 404 Not Found: Station not found or no data available
• 429 Too Many Requests: API rate limit exceeded
• 500 Internal Server Error: WeatherXM service temporarily unavailable
• Network Errors: Connection issues

Troubleshooting

Common Error Messages

Error: "Invalid API key"

• Double-check your API key from pro.weatherxm.com
• Ensure the API key is properly set in your environment

Error: "Station not found"

• Try searching for stations first: "Find weather stations near [your location]"
• Use the station IDs returned by the search

Error: "API rate limit exceeded"

• Wait a few minutes before trying again
• Consider upgrading your WeatherXM Pro plan

Error: "WeatherXM service temporarily unavailable"

• The WeatherXM service may be experiencing issues
• Try again later

Common Issues

1. Missing API Key: The server requires a valid WeatherXM Pro API key
2. Invalid API Key: Double-check the key from your WeatherXM Pro account
3. Network Issues: Ensure you have internet connectivity
4. Rate Limiting: You may have exceeded your API quota

Development

Running in Development Mode

Option A: Using Smithery (Default)

npm run dev

Option B: Using TypeScript with tsx

npm run dev:tsc

Note: The dev:tsc command uses tsx for fast TypeScript execution without compilation. Use this for development if you prefer not to use Smithery.

Building for Production

npm run build

API Reference

This server uses the WeatherXM Pro API. For detailed API documentation, visit:

• WeatherXM Pro API Documentation

Key Endpoints Used

• GET /stations/{station_id}/latest - Get latest observation
• GET /stations/{station_id}/forecast/hourly - Get hourly forecast
• GET /stations/{station_id}/forecast/daily - Get daily forecast
• GET /stations/{station_id}/historical - Get historical data
• GET /alerts - Get weather alerts
• GET /stations - Find nearby stations
• GET /stations/search - Search for stations
• GET /cells - Get weather cells

License

ISC

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues related to:

• WeatherXM Pro API: Contact WeatherXM support at pro.weatherxm.com
• MCP Server Issues: Check the main README.md for more details
• Weather Data: Check the data quality scores provided by the server
• Configuration Issues: Review the Configuration and Troubleshooting sections above