mcp-name: io.github.isdaniel/mcpweatherserver A Model Context Protocol (MCP) server that provides weather information using the Open-Meteo API. This server supports multiple transport modes: standard stdio, HTTP Server-Sent Events (SSE), and the new Streamable HTTP protocol for web-based integration. Get current weather information with comprehensive metrics: Temperature, humidity, dew point Wind
Add this skill
npx mdskills install isdaniel/mcp-weather-serverComprehensive weather and air quality MCP server with excellent documentation and flexible transport modes
1[](https://smithery.ai/server/@isdaniel/mcp_weather_server)2[](https://pypi.org/project/mcp-weather-server/)3[](https://pypi.org/project/mcp-weather-server/)4[](https://pepy.tech/projects/mcp-weather-server)5[](https://hub.docker.com/r/dog830228/mcp_weather_server)67<a href="https://glama.ai/mcp/servers/@isdaniel/mcp_weather_server">8 <img width="380" height="200" src="https://glama.ai/mcp/servers/@isdaniel/mcp_weather_server/badge" />9</a>1011# Weather MCP Server1213mcp-name: io.github.isdaniel/mcp_weather_server1415A Model Context Protocol (MCP) server that provides weather information using the Open-Meteo API. This server supports multiple transport modes: standard stdio, HTTP Server-Sent Events (SSE), and the new Streamable HTTP protocol for web-based integration.1617## Features1819### Weather & Air Quality20* Get current weather information with comprehensive metrics:21 * Temperature, humidity, dew point22 * Wind speed, direction, and gusts23 * Precipitation (rain/snow) and probability24 * Atmospheric pressure and cloud cover25 * UV index and visibility26 * "Feels like" temperature27* Get weather data for a date range with hourly details28* Get air quality information including:29 * PM2.5 and PM10 particulate matter30 * Ozone, nitrogen dioxide, carbon monoxide31 * Sulfur dioxide, ammonia, dust32 * Aerosol optical depth33 * Health advisories and recommendations3435### Time & Timezone36* Get current date/time in any timezone37* Convert time between timezones38* Get timezone information3940### Transport Modes41* Multiple transport modes:42 * **stdio** - Standard MCP for desktop clients (Claude Desktop, etc.)43 * **SSE** - Server-Sent Events for web applications44 * **streamable-http** - Modern MCP Streamable HTTP protocol with stateful/stateless options45* RESTful API endpoints via Starlette integration4647## Installation4849### Installing via Smithery5051To install Weather MCP Server automatically via [Smithery](https://smithery.ai/server/@isdaniel/mcp_weather_server):5253```bash54npx -y @smithery/cli install @isdaniel/mcp_weather_server55```5657### Standard Installation (for MCP clients like Claude Desktop)5859This package can be installed using pip:6061```bash62pip install mcp_weather_server63```6465### Manual Configuration for MCP Clients6667This server is designed to be installed manually by adding its configuration to the `cline_mcp_settings.json` file.68691. Add the following entry to the `mcpServers` object in your `cline_mcp_settings.json` file:7071```json72{73 "mcpServers": {74 "weather": {75 "command": "python",76 "args": [77 "-m",78 "mcp_weather_server"79 ],80 "disabled": false,81 "autoApprove": []82 }83 }84}85```86872. Save the `cline_mcp_settings.json` file.8889### HTTP Server Installation (for web applications)9091For HTTP SSE or Streamable HTTP support, you'll need additional dependencies:9293```bash94pip install mcp_weather_server starlette uvicorn95```9697## Server Modes9899This MCP server supports **stdio**, **SSE**, and **streamable-http** modes in a single unified server:100101### Mode Comparison102103| Feature | stdio | SSE | streamable-http |104|---------|-------|-----|-----------------|105| **Use Case** | Desktop MCP clients | Web applications (legacy) | Web applications (modern) |106| **Protocol** | Standard I/O streams | Server-Sent Events | MCP Streamable HTTP |107| **Session Management** | N/A | Stateful | Stateful or Stateless |108| **Endpoints** | N/A | `/sse`, `/messages/` | `/mcp` (single) |109| **Best For** | Claude Desktop, Cline | Browser-based apps | Modern web apps, APIs |110| **State Options** | N/A | Stateful only | Stateful or Stateless |111112### 1. Standard MCP Mode (Default)113The standard mode communicates via stdio and is compatible with MCP clients like Claude Desktop.114115```bash116# Default mode (stdio)117python -m mcp_weather_server118119# Explicitly specify stdio mode120python -m mcp_weather_server.server --mode stdio121```122123### 2. HTTP SSE Mode (Web Applications)124The SSE mode runs an HTTP server that provides MCP functionality via Server-Sent Events, making it accessible to web applications.125126```bash127# Start SSE server on default host/port (0.0.0.0:8080)128python -m mcp_weather_server --mode sse129130# Specify custom host and port131python -m mcp_weather_server --mode sse --host localhost --port 3000132133# Enable debug mode134python -m mcp_weather_server --mode sse --debug135```136137**SSE Endpoints:**138- `GET /sse` - SSE endpoint for MCP communication139- `POST /messages/` - Message endpoint for sending MCP requests140141### 3. Streamable HTTP Mode (Modern MCP Protocol)142The streamable-http mode implements the new MCP Streamable HTTP protocol with a single `/mcp` endpoint. This mode supports both stateful (default) and stateless operations.143144```bash145# Start streamable HTTP server on default host/port (0.0.0.0:8080)146python -m mcp_weather_server --mode streamable-http147148# Specify custom host and port149python -m mcp_weather_server --mode streamable-http --host localhost --port 3000150151# Enable stateless mode (creates fresh transport per request, no session tracking)152python -m mcp_weather_server --mode streamable-http --stateless153154# Enable debug mode155python -m mcp_weather_server --mode streamable-http --debug156```157158**Streamable HTTP Features:**159- **Stateful mode (default)**: Maintains session state across requests using session IDs160- **Stateless mode**: Creates fresh transport per request with no session tracking161- **Single endpoint**: All MCP communication happens through `/mcp`162- **Modern protocol**: Implements the latest MCP Streamable HTTP specification163164**Streamable HTTP Endpoint:**165- `POST /mcp` - Single endpoint for all MCP communication (initialize, tools/list, tools/call, etc.)166167**Command Line Options:**168```169--mode {stdio,sse,streamable-http} Server mode: stdio (default), sse, or streamable-http170--host HOST Host to bind to (HTTP modes only, default: 0.0.0.0)171--port PORT Port to listen on (HTTP modes only, default: 8080)172--stateless Run in stateless mode (streamable-http only)173--debug Enable debug mode174```175176**Example SSE Usage:**177```javascript178// Connect to SSE endpoint179const eventSource = new EventSource('http://localhost:8080/sse');180181// Send MCP tool request182fetch('http://localhost:8080/messages/', {183 method: 'POST',184 headers: { 'Content-Type': 'application/json' },185 body: JSON.stringify({186 type: 'tool_call',187 tool: 'get_weather',188 arguments: { city: 'Tokyo' }189 })190});191```192193**Example Streamable HTTP Usage:**194```javascript195// Initialize session and call tool using Streamable HTTP protocol196async function callWeatherTool() {197 const response = await fetch('http://localhost:8080/mcp', {198 method: 'POST',199 headers: {200 'Content-Type': 'application/json'201 },202 body: JSON.stringify({203 jsonrpc: '2.0',204 method: 'tools/call',205 params: {206 name: 'get_current_weather',207 arguments: { city: 'Tokyo' }208 },209 id: 1210 })211 });212213 const result = await response.json();214 console.log(result);215}216```217218## Configuration219220This server does not require an API key. It uses the Open-Meteo API, which is free and open-source.221222## Usage223224This server provides several tools for weather and time-related operations:225226### Available Tools227228#### Weather Tools2291. **`get_current_weather`** - Get current weather for a city with comprehensive metrics2302. **`get_weather_by_datetime_range`** - Get weather data for a date range with hourly details2313. **`get_weather_details`** - Get detailed weather information as structured JSON data232233#### Air Quality Tools2344. **`get_air_quality`** - Get air quality information with pollutant levels and health advice2355. **`get_air_quality_details`** - Get detailed air quality data as structured JSON236237#### Time & Timezone Tools2386. **`get_current_datetime`** - Get current time in any timezone2397. **`get_timezone_info`** - Get timezone information2408. **`convert_time`** - Convert time between timezones241242### Tool Details243244#### `get_current_weather`245246Retrieves comprehensive current weather information for a given city with enhanced metrics.247248**Parameters:**249- `city` (string, required): The name of the city (English names only)250251**Returns:** Detailed weather data including:252- Temperature and "feels like" temperature253- Humidity, dew point254- Wind speed, direction (as compass direction), and gusts255- Precipitation details (rain/snow) and probability256- Atmospheric pressure and cloud cover257- UV index with warning levels258- Visibility259260**Example Response:**261```262The weather in Tokyo is Mainly clear with a temperature of 22.5°C (feels like 21.0°C),263relative humidity at 65%, and dew point at 15.5°C. Wind is blowing from the NE at 12.5 km/h264with gusts up to 18.5 km/h. Atmospheric pressure is 1013.2 hPa with 25% cloud cover.265UV index is 5.5 (Moderate). Visibility is 10.0 km.266```267268#### `get_weather_by_datetime_range`269270Retrieves hourly weather information with comprehensive metrics for a specified city between start and end dates.271272**Parameters:**273- `city` (string, required): The name of the city (English names only)274- `start_date` (string, required): Start date in format YYYY-MM-DD (ISO 8601)275- `end_date` (string, required): End date in format YYYY-MM-DD (ISO 8601)276277**Returns:** Comprehensive weather analysis including:278- Hourly weather data with all enhanced metrics279- Temperature trends (highs, lows, averages)280- Precipitation patterns and probabilities281- Wind conditions assessment282- UV index trends283- Weather warnings and recommendations284285**Example Response:**286```287[Analysis of weather trends over 2024-01-01 to 2024-01-07]288- Temperature ranges from 5°C to 15°C289- Precipitation expected on Jan 3rd and 5th (60% probability)290- Wind speeds averaging 15 km/h from SW direction291- UV index moderate (3-5) throughout the period292- Recommendation: Umbrella needed for midweek293```294295#### `get_weather_details`296297Get detailed weather information for a specified city as structured JSON data for programmatic use.298299**Parameters:**300- `city` (string, required): The name of the city (English names only)301302**Returns:** Raw JSON data with all weather metrics suitable for processing and analysis303304#### `get_air_quality`305306Get current air quality information for a specified city with pollutant levels and health advisories.307308**Parameters:**309- `city` (string, required): The name of the city (English names only)310- `variables` (array, optional): Specific pollutants to retrieve. Options:311 - `pm10` - Particulate matter ≤10μm312 - `pm2_5` - Particulate matter ≤2.5μm313 - `carbon_monoxide` - CO levels314 - `nitrogen_dioxide` - NO2 levels315 - `ozone` - O3 levels316 - `sulphur_dioxide` - SO2 levels317 - `ammonia` - NH3 levels318 - `dust` - Dust particle levels319 - `aerosol_optical_depth` - Atmospheric turbidity320321**Returns:** Comprehensive air quality report including:322- Current pollutant levels with units323- Air quality classification (Good/Moderate/Unhealthy/Hazardous)324- Health recommendations for general population325- Specific warnings for sensitive groups326- Comparison with WHO and EPA standards327328**Example Response:**329```330Air quality in Beijing (lat: 39.90, lon: 116.41):331PM2.5: 45.3 μg/m³ (Unhealthy for Sensitive Groups)332PM10: 89.2 μg/m³ (Moderate)333Ozone (O3): 52.1 μg/m³334Nitrogen Dioxide (NO2): 38.5 μg/m³335Carbon Monoxide (CO): 420.0 μg/m³336337Health Advice: Sensitive groups (children, elderly, people with respiratory conditions)338should limit outdoor activities.339```340341#### `get_air_quality_details`342343Get detailed air quality information as structured JSON data for programmatic analysis.344345**Parameters:**346- `city` (string, required): The name of the city (English names only)347- `variables` (array, optional): Specific pollutants to retrieve (same options as `get_air_quality`)348349**Returns:** Raw JSON data with complete air quality metrics and hourly data350351#### `get_current_datetime`352353Retrieves the current time in a specified timezone.354355**Parameters:**356- `timezone_name` (string, required): IANA timezone name (e.g., 'America/New_York', 'Europe/London'). Use UTC if no timezone provided.357358**Returns:** Current date and time in the specified timezone359360**Example:**361```json362{363 "timezone": "America/New_York",364 "current_time": "2024-01-15T14:30:00-05:00",365 "utc_time": "2024-01-15T19:30:00Z"366}367```368369#### `get_timezone_info`370371Get information about a specific timezone.372373**Parameters:**374- `timezone_name` (string, required): IANA timezone name375376**Returns:** Timezone details including offset and DST information377378#### `convert_time`379380Convert time from one timezone to another.381382**Parameters:**383- `time_str` (string, required): Time to convert (ISO format)384- `from_timezone` (string, required): Source timezone385- `to_timezone` (string, required): Target timezone386387**Returns:** Converted time in target timezone388389## MCP Client Usage Examples390391### Using with Claude Desktop or MCP Clients392393```xml394<use_mcp_tool>395<server_name>weather</server_name>396<tool_name>get_current_weather</tool_name>397<arguments>398{399 "city": "Tokyo"400}401</arguments>402</use_mcp_tool>403```404405```xml406<use_mcp_tool>407<server_name>weather</server_name>408<tool_name>get_weather_by_datetime_range</tool_name>409<arguments>410{411 "city": "Paris",412 "start_date": "2024-01-01",413 "end_date": "2024-01-07"414}415</arguments>416</use_mcp_tool>417```418419```xml420<use_mcp_tool>421<server_name>weather</server_name>422<tool_name>get_current_datetime</tool_name>423<arguments>424{425 "timezone_name": "Europe/Paris"426}427</arguments>428</use_mcp_tool>429```430431```xml432<use_mcp_tool>433<server_name>weather</server_name>434<tool_name>get_air_quality</tool_name>435<arguments>436{437 "city": "Beijing"438}439</arguments>440</use_mcp_tool>441```442443```xml444<use_mcp_tool>445<server_name>weather</server_name>446<tool_name>get_air_quality</tool_name>447<arguments>448{449 "city": "Los Angeles",450 "variables": ["pm2_5", "pm10", "ozone"]451}452</arguments>453</use_mcp_tool>454```455456## Web Integration (SSE Mode)457458When running in SSE mode, you can integrate the weather server with web applications:459460### HTML/JavaScript Example461462```html463<!DOCTYPE html>464<html>465<head>466 <title>Weather MCP Client</title>467</head>468<body>469 <div id="weather-data"></div>470 <script>471 // Connect to SSE endpoint472 const eventSource = new EventSource('http://localhost:8080/sse');473474 eventSource.onmessage = function(event) {475 const data = JSON.parse(event.data);476 document.getElementById('weather-data').innerHTML = JSON.stringify(data, null, 2);477 };478479 // Function to get weather480 async function getWeather(city) {481 const response = await fetch('http://localhost:8080/messages/', {482 method: 'POST',483 headers: { 'Content-Type': 'application/json' },484 body: JSON.stringify({485 jsonrpc: '2.0',486 method: 'tools/call',487 params: {488 name: 'get_current_weather',489 arguments: { city: city }490 },491 id: 1492 })493 });494 }495496 // Example: Get weather for Tokyo497 getWeather('Tokyo');498499 // Example: Get air quality500 async function getAirQuality(city) {501 const response = await fetch('http://localhost:8080/messages/', {502 method: 'POST',503 headers: { 'Content-Type': 'application/json' },504 body: JSON.stringify({505 jsonrpc: '2.0',506 method: 'tools/call',507 params: {508 name: 'get_air_quality',509 arguments: { city: city }510 },511 id: 2512 })513 });514 }515516 getAirQuality('Beijing');517 </script>518</body>519</html>520```521522## Docker Deployment523524The project is available as a Docker image on Docker Hub and includes configurations for easy deployment.525526### Quick Start with Docker Hub527528Pull and run the latest image directly from Docker Hub:529530```bash531# Pull the latest image532docker pull dog830228/mcp_weather_server:latest533534# Run in stdio mode (default)535docker run dog830228/mcp_weather_server:latest536537# Run in SSE mode on port 8080538docker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode sse539540# Run in streamable-http mode on port 8080541docker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode streamable-http542543# Pull a specific version544docker pull dog830228/mcp_weather_server:0.5.0545docker run -p 8080:8080 dog830228/mcp_weather_server:0.5.0 --mode sse546```547548### Available Docker Images549550- **Latest**: `dog830228/mcp_weather_server:latest`551- **Versioned**: `dog830228/mcp_weather_server:<version>` (e.g., `0.5.0`)552553Images are automatically built and published when new versions are released.554555### Building from Source556557If you want to build the Docker image yourself:558559#### Standard Build560```bash561# Build562docker build -t mcp-weather-server:sse .563564# Run (port will be read from PORT env var, defaults to 8081)565docker run -p 8081:8081 mcp-weather-server:sse566567# Run with custom port568docker run -p 8080:8080 mcp-weather-server:local --mode sse569```570571#### Streamable HTTP Build572```bash573# Build using streamable-http Dockerfile574docker build -f Dockerfile.streamable-http -t mcp-weather-server:streamable-http .575576# Run in stateful mode577docker run -p 8080:8080 mcp-weather-server:streamable-http578579# Run in stateless mode580docker run -p 8080:8080 -e STATELESS=true mcp-weather-server:streamable-http581```582583## Development584585### Project Structure586587```588mcp_weather_server/589├── src/590│ └── mcp_weather_server/591│ ├── __init__.py592│ ├── __main__.py # Main MCP server entry point593│ ├── server.py # Unified server (stdio, SSE, streamable-http)594│ ├── utils.py # Utility functions595│ └── tools/ # Tool implementations596│ ├── __init__.py597│ ├── toolhandler.py # Base tool handler598│ ├── tools_weather.py # Weather-related tools599│ ├── tools_time.py # Time-related tools600│ ├── tools_air_quality.py # Air quality tools601│ ├── weather_service.py # Weather API service602│ └── air_quality_service.py # Air quality API service603├── tests/604├── Dockerfile # Docker configuration for SSE mode605├── Dockerfile.streamable-http # Docker configuration for streamable-http mode606├── pyproject.toml607├── requirements.txt608└── README.md609```610611### Running for Development612613#### Standard MCP Mode (stdio)614```bash615# From project root616python -m mcp_weather_server617618# Or with PYTHONPATH619export PYTHONPATH="/path/to/mcp_weather_server/src"620python -m mcp_weather_server621```622623#### SSE Server Mode624```bash625# From project root626python -m mcp_weather_server --mode sse --host 0.0.0.0 --port 8080627628# With custom host/port629python -m mcp_weather_server --mode sse --host localhost --port 3000630```631632#### Streamable HTTP Mode633```bash634# Stateful mode (default)635python -m mcp_weather_server --mode streamable-http --host 0.0.0.0 --port 8080636637# With debug logging638python -m mcp_weather_server --mode streamable-http --debug639```640641### Adding New Tools642643To add new weather or time-related tools:6446451. Create a new tool handler in the appropriate file under `tools/`6462. Inherit from the `ToolHandler` base class6473. Implement the required methods (`get_name`, `get_description`, `call`)6484. Register the tool in `server.py`649650## Dependencies651652### Core Dependencies653- `mcp>=1.0.0` - Model Context Protocol implementation654- `httpx>=0.28.1` - HTTP client for API requests655- `python-dateutil>=2.8.2` - Date/time parsing utilities656657### SSE Server Dependencies658- `starlette` - ASGI web framework659- `uvicorn` - ASGI server660661### Development Dependencies662- `pytest` - Testing framework663664## API Data Sources665666This server uses free and open-source APIs:667668### Weather Data: [Open-Meteo Weather API](https://open-meteo.com/)669- Free and open-source670- No API key required671- Provides accurate weather forecasts672- Supports global locations673- Historical and current weather data674- Comprehensive metrics (wind, precipitation, UV, visibility)675676### Air Quality Data:677- Free and open-source678- No API key required679- Real-time air quality data680- Multiple pollutant measurements (PM2.5, PM10, O3, NO2, CO, SO2)681- Global coverage682- Health-based air quality indices683684## Troubleshooting685686### Common Issues687688**1. City not found**689- Ensure city names are in English690- Try using the full city name or include country (e.g., "Paris, France")691- Check spelling of city names692693**2. HTTP Server not accessible (SSE or Streamable HTTP)**694- Verify the server is running with the correct mode:695 - SSE: `python -m mcp_weather_server --mode sse`696 - Streamable HTTP: `python -m mcp_weather_server --mode streamable-http`697- Check firewall settings for the specified port698- Ensure all dependencies are installed: `pip install starlette uvicorn`699- Verify the correct endpoint:700 - SSE: `http://localhost:8080/sse` and `http://localhost:8080/messages/`701 - Streamable HTTP: `http://localhost:8080/mcp`702703**3. MCP Client connection issues**704- Verify Python path in MCP client configuration705- Check that `mcp_weather_server` package is installed706- Ensure Python environment has required dependencies707708**4. Date format errors**709- Use ISO 8601 format for dates: YYYY-MM-DD710- Ensure start_date is before end_date711- Check that dates are not too far in the future712713### Error Responses714715The server returns structured error messages:716717```json718{719 "error": "Could not retrieve coordinates for InvalidCity."720}721```722723724<!-- Need to add this line for MCP registry publication -->725<!-- mcp-name: io.github.isdaniel/mcp_weather_server -->726
Full transparency — inspect the skill content before installing.