README.md•14.2 kB
# WeatherXM Pro MCP Server
[](https://smithery.ai/server/@oharkins/weatherxm-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](https://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](https://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:
```bash
# 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)**
```bash
export WEATHERXM_API_KEY="your_api_key_here"
```
**Option B: MCP Client Configuration**
For Claude Desktop or other MCP clients, add to your configuration:
```json
{
"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:
```bash
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:
```json
{
"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:
```json
{
"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:
```json
{
"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:
```bash
git clone <repository-url>
cd weatherxm-mcp-server
```
2. Install dependencies:
```bash
npm install
```
3. Build the server:
**Option A: Using Smithery (Default)**
```bash
npm run build
```
**Option B: Using Traditional TypeScript**
```bash
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:**
```bash
npm run dev
```
**Build for production:**
```bash
npm run build
```
### Using Local Runner
For local development and testing without Smithery:
**Set your API key:**
```bash
export WEATHERXM_API_KEY="your_api_key_here"
```
**Run the local runner:**
```bash
npm run runner
```
**Or run directly with tsx:**
```bash
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)**
```bash
npm run dev
```
**Option B: Using TypeScript with tsx**
```bash
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
```bash
npm run build
```
## API Reference
This server uses the WeatherXM Pro API. For detailed API documentation, visit:
- [WeatherXM Pro API Documentation](https://pro.weatherxm.com/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