{
"markdown": "[](https://smithery.ai/server/@isdaniel/mcp_weather_server)\n[](https://pypi.org/project/mcp-weather-server/)\n[](https://pypi.org/project/mcp-weather-server/)\n[](https://pepy.tech/projects/mcp-weather-server)\n[](https://hub.docker.com/r/dog830228/mcp_weather_server)\n\n\n ![](\"https://glama.ai/mcp/servers/@isdaniel/mcp_weather_server/badge\")
\n\n\n# Weather MCP Server\n\nmcp-name: io.github.isdaniel/mcp_weather_server\n\nA 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.\n\n## Features\n\n### Weather & Air Quality\n* Get current weather information with comprehensive metrics:\n * Temperature, humidity, dew point\n * Wind speed, direction, and gusts\n * Precipitation (rain/snow) and probability\n * Atmospheric pressure and cloud cover\n * UV index and visibility\n * \"Feels like\" temperature\n * Sunrise and sunset times (local time at the location)\n* Get weather data for a date range with hourly details and daily sunrise/sunset times\n* Get air quality information including:\n * PM2.5 and PM10 particulate matter\n * Ozone, nitrogen dioxide, carbon monoxide\n * Sulfur dioxide, ammonia, dust\n * Aerosol optical depth\n * Health advisories and recommendations\n\n### Time & Timezone\n* Get current date/time in any timezone\n* Convert time between timezones\n* Get timezone information\n\n### Transport Modes\n* Multiple transport modes:\n * **stdio** - Standard MCP for desktop clients (Claude Desktop, etc.)\n * **SSE** - Server-Sent Events for web applications\n * **streamable-http** - Modern MCP Streamable HTTP protocol with stateful/stateless options\n* RESTful API endpoints via Starlette integration\n\n## Installation\n\n### Installing via Smithery\n\nTo install Weather MCP Server automatically via [Smithery](https://smithery.ai/server/@isdaniel/mcp_weather_server):\n\n```bash\nnpx -y @smithery/cli install @isdaniel/mcp_weather_server\n```\n\n### Standard Installation (for MCP clients like Claude Desktop)\n\nThis package can be installed using pip:\n\n```bash\npip install mcp_weather_server\n```\n\n### Manual Configuration for MCP Clients\n\nThis server is designed to be installed manually by adding its configuration to the `cline_mcp_settings.json` file.\n\n1. Add the following entry to the `mcpServers` object in your `cline_mcp_settings.json` file:\n\n```json\n{\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"python\",\n \"args\": [\n \"-m\",\n \"mcp_weather_server\"\n ],\n \"disabled\": false,\n \"autoApprove\": []\n }\n }\n}\n```\n\n2. Save the `cline_mcp_settings.json` file.\n\n### HTTP Server Installation (for web applications)\n\nFor HTTP SSE or Streamable HTTP support, you'll need additional dependencies:\n\n```bash\npip install mcp_weather_server starlette uvicorn\n```\n\n## Server Modes\n\nThis MCP server supports **stdio**, **SSE**, and **streamable-http** modes in a single unified server:\n\n### Mode Comparison\n\n| Feature | stdio | SSE | streamable-http |\n|---------|-------|-----|-----------------|\n| **Use Case** | Desktop MCP clients | Web applications (legacy) | Web applications (modern) |\n| **Protocol** | Standard I/O streams | Server-Sent Events | MCP Streamable HTTP |\n| **Session Management** | N/A | Stateful | Stateful or Stateless |\n| **Endpoints** | N/A | `/sse`, `/messages/` | `/mcp` (single) |\n| **Best For** | Claude Desktop, Cline | Browser-based apps | Modern web apps, APIs |\n| **State Options** | N/A | Stateful only | Stateful or Stateless |\n\n### 1. Standard MCP Mode (Default)\nThe standard mode communicates via stdio and is compatible with MCP clients like Claude Desktop.\n\n```bash\n# Default mode (stdio)\npython -m mcp_weather_server\n\n# Explicitly specify stdio mode\npython -m mcp_weather_server.server --mode stdio\n```\n\n### 2. HTTP SSE Mode (Web Applications)\nThe SSE mode runs an HTTP server that provides MCP functionality via Server-Sent Events, making it accessible to web applications.\n\n```bash\n# Start SSE server on default host/port (0.0.0.0:8080)\npython -m mcp_weather_server --mode sse\n\n# Specify custom host and port\npython -m mcp_weather_server --mode sse --host localhost --port 3000\n\n# Enable debug mode\npython -m mcp_weather_server --mode sse --debug\n```\n\n**SSE Endpoints:**\n- `GET /sse` - SSE endpoint for MCP communication\n- `POST /messages/` - Message endpoint for sending MCP requests\n\n### 3. Streamable HTTP Mode (Modern MCP Protocol)\nThe streamable-http mode implements the new MCP Streamable HTTP protocol with a single `/mcp` endpoint. This mode supports both stateful (default) and stateless operations.\n\n```bash\n# Start streamable HTTP server on default host/port (0.0.0.0:8080)\npython -m mcp_weather_server --mode streamable-http\n\n# Specify custom host and port\npython -m mcp_weather_server --mode streamable-http --host localhost --port 3000\n\n# Enable stateless mode (creates fresh transport per request, no session tracking)\npython -m mcp_weather_server --mode streamable-http --stateless\n\n# Enable debug mode\npython -m mcp_weather_server --mode streamable-http --debug\n```\n\n**Streamable HTTP Features:**\n- **Stateful mode (default)**: Maintains session state across requests using session IDs\n- **Stateless mode**: Creates fresh transport per request with no session tracking\n- **Single endpoint**: All MCP communication happens through `/mcp`\n- **Modern protocol**: Implements the latest MCP Streamable HTTP specification\n\n**Streamable HTTP Endpoint:**\n- `POST /mcp` - Single endpoint for all MCP communication (initialize, tools/list, tools/call, etc.)\n\n**Command Line Options:**\n```\n--mode {stdio,sse,streamable-http} Server mode: stdio (default), sse, or streamable-http\n--host HOST Host to bind to (HTTP modes only, default: 0.0.0.0)\n--port PORT Port to listen on (HTTP modes only, default: 8080)\n--stateless Run in stateless mode (streamable-http only)\n--debug Enable debug mode\n```\n\n**Example SSE Usage:**\n```javascript\n// Connect to SSE endpoint\nconst eventSource = new EventSource('http://localhost:8080/sse');\n\n// Send MCP tool request\nfetch('http://localhost:8080/messages/', {\n method: 'POST',\n headers: { 'Content-Type': 'application/json' },\n body: JSON.stringify({\n type: 'tool_call',\n tool: 'get_weather',\n arguments: { city: 'Tokyo' }\n })\n});\n```\n\n**Example Streamable HTTP Usage:**\n```javascript\n// Initialize session and call tool using Streamable HTTP protocol\nasync function callWeatherTool() {\n const response = await fetch('http://localhost:8080/mcp', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({\n jsonrpc: '2.0',\n method: 'tools/call',\n params: {\n name: 'get_current_weather',\n arguments: { city: 'Tokyo' }\n },\n id: 1\n })\n });\n\n const result = await response.json();\n console.log(result);\n}\n```\n\n## Configuration\n\nThis server does not require an API key. It uses the Open-Meteo API, which is free and open-source.\n\n## Usage\n\nThis server provides several tools for weather and time-related operations:\n\n### Available Tools\n\n#### Weather Tools\n1. **`get_current_weather`** - Get current weather for a city with comprehensive metrics\n2. **`get_weather_by_datetime_range`** - Get weather data for a date range with hourly details\n3. **`get_weather_details`** - Get detailed weather information as structured JSON data\n\n#### Air Quality Tools\n4. **`get_air_quality`** - Get air quality information with pollutant levels and health advice\n5. **`get_air_quality_details`** - Get detailed air quality data as structured JSON\n\n#### Time & Timezone Tools\n6. **`get_current_datetime`** - Get current time in any timezone\n7. **`get_timezone_info`** - Get timezone information\n8. **`convert_time`** - Convert time between timezones\n\n### Tool Details\n\n#### `get_current_weather`\n\nRetrieves comprehensive current weather information for a given city with enhanced metrics.\n\n**Parameters:**\n- `city` (string, required): The name of the city (English names only)\n\n**Returns:** Detailed weather data including:\n- Temperature and \"feels like\" temperature\n- Humidity, dew point\n- Wind speed, direction (as compass direction), and gusts\n- Precipitation details (rain/snow) and probability\n- Atmospheric pressure and cloud cover\n- UV index with warning levels\n- Visibility\n\n**Example Response:**\n```\nThe weather in Tokyo is Mainly clear with a temperature of 22.5°C (feels like 21.0°C),\nrelative humidity at 65%, and dew point at 15.5°C. Wind is blowing from the NE at 12.5 km/h\nwith gusts up to 18.5 km/h. Atmospheric pressure is 1013.2 hPa with 25% cloud cover.\nUV index is 5.5 (Moderate). Visibility is 10.0 km.\n```\n\n#### `get_weather_by_datetime_range`\n\nRetrieves hourly weather information with comprehensive metrics for a specified city between start and end dates.\n\n**Parameters:**\n- `city` (string, required): The name of the city (English names only)\n- `start_date` (string, required): Start date in format YYYY-MM-DD (ISO 8601)\n- `end_date` (string, required): End date in format YYYY-MM-DD (ISO 8601)\n\n**Returns:** Comprehensive weather analysis including:\n- Hourly weather data with all enhanced metrics\n- Temperature trends (highs, lows, averages)\n- Precipitation patterns and probabilities\n- Wind conditions assessment\n- UV index trends\n- Weather warnings and recommendations\n\n**Example Response:**\n```\n[Analysis of weather trends over 2024-01-01 to 2024-01-07]\n- Temperature ranges from 5°C to 15°C\n- Precipitation expected on Jan 3rd and 5th (60% probability)\n- Wind speeds averaging 15 km/h from SW direction\n- UV index moderate (3-5) throughout the period\n- Recommendation: Umbrella needed for midweek\n```\n\n#### `get_weather_details`\n\nGet detailed weather information for a specified city as structured JSON data for programmatic use.\n\n**Parameters:**\n- `city` (string, required): The name of the city (English names only)\n\n**Returns:** Raw JSON data with all weather metrics suitable for processing and analysis\n\n#### `get_air_quality`\n\nGet current air quality information for a specified city with pollutant levels and health advisories.\n\n**Parameters:**\n- `city` (string, required): The name of the city (English names only)\n- `variables` (array, optional): Specific pollutants to retrieve. Options:\n - `pm10` - Particulate matter ≤10μm\n - `pm2_5` - Particulate matter ≤2.5μm\n - `carbon_monoxide` - CO levels\n - `nitrogen_dioxide` - NO2 levels\n - `ozone` - O3 levels\n - `sulphur_dioxide` - SO2 levels\n - `ammonia` - NH3 levels\n - `dust` - Dust particle levels\n - `aerosol_optical_depth` - Atmospheric turbidity\n\n**Returns:** Comprehensive air quality report including:\n- Current pollutant levels with units\n- Air quality classification (Good/Moderate/Unhealthy/Hazardous)\n- Health recommendations for general population\n- Specific warnings for sensitive groups\n- Comparison with WHO and EPA standards\n\n**Example Response:**\n```\nAir quality in Beijing (lat: 39.90, lon: 116.41):\nPM2.5: 45.3 μg/m³ (Unhealthy for Sensitive Groups)\nPM10: 89.2 μg/m³ (Moderate)\nOzone (O3): 52.1 μg/m³\nNitrogen Dioxide (NO2): 38.5 μg/m³\nCarbon Monoxide (CO): 420.0 μg/m³\n\nHealth Advice: Sensitive groups (children, elderly, people with respiratory conditions)\nshould limit outdoor activities.\n```\n\n#### `get_air_quality_details`\n\nGet detailed air quality information as structured JSON data for programmatic analysis.\n\n**Parameters:**\n- `city` (string, required): The name of the city (English names only)\n- `variables` (array, optional): Specific pollutants to retrieve (same options as `get_air_quality`)\n\n**Returns:** Raw JSON data with complete air quality metrics and hourly data\n\n#### `get_current_datetime`\n\nRetrieves the current time in a specified timezone.\n\n**Parameters:**\n- `timezone_name` (string, required): IANA timezone name (e.g., 'America/New_York', 'Europe/London'). Use UTC if no timezone provided.\n\n**Returns:** Current date and time in the specified timezone\n\n**Example:**\n```json\n{\n \"timezone\": \"America/New_York\",\n \"current_time\": \"2024-01-15T14:30:00-05:00\",\n \"utc_time\": \"2024-01-15T19:30:00Z\"\n}\n```\n\n#### `get_timezone_info`\n\nGet information about a specific timezone.\n\n**Parameters:**\n- `timezone_name` (string, required): IANA timezone name\n\n**Returns:** Timezone details including offset and DST information\n\n#### `convert_time`\n\nConvert time from one timezone to another.\n\n**Parameters:**\n- `time_str` (string, required): Time to convert (ISO format)\n- `from_timezone` (string, required): Source timezone\n- `to_timezone` (string, required): Target timezone\n\n**Returns:** Converted time in target timezone\n\n## MCP Client Usage Examples\n\n### Using with Claude Desktop or MCP Clients\n\n```xml\n\nweather\nget_current_weather\n\n{\n \"city\": \"Tokyo\"\n}\n\n\n```\n\n```xml\n\nweather\nget_weather_by_datetime_range\n\n{\n \"city\": \"Paris\",\n \"start_date\": \"2024-01-01\",\n \"end_date\": \"2024-01-07\"\n}\n\n\n```\n\n```xml\n\nweather\nget_current_datetime\n\n{\n \"timezone_name\": \"Europe/Paris\"\n}\n\n\n```\n\n```xml\n\nweather\nget_air_quality\n\n{\n \"city\": \"Beijing\"\n}\n\n\n```\n\n```xml\n\nweather\nget_air_quality\n\n{\n \"city\": \"Los Angeles\",\n \"variables\": [\"pm2_5\", \"pm10\", \"ozone\"]\n}\n\n\n```\n\n## Web Integration (SSE Mode)\n\nWhen running in SSE mode, you can integrate the weather server with web applications:\n\n### HTML/JavaScript Example\n\n```html\n\n\n\n Weather MCP Client\n\n\n \n \n\n\n```\n\n## Docker Deployment\n\nThe project is available as a Docker image on Docker Hub and includes configurations for easy deployment.\n\n### Quick Start with Docker Hub\n\nPull and run the latest image directly from Docker Hub:\n\n```bash\n# Pull the latest image\ndocker pull dog830228/mcp_weather_server:latest\n\n# Run in stdio mode (default)\ndocker run dog830228/mcp_weather_server:latest\n\n# Run in SSE mode on port 8080\ndocker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode sse\n\n# Run in streamable-http mode on port 8080\ndocker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode streamable-http\n\n# Pull a specific version\ndocker pull dog830228/mcp_weather_server:0.5.0\ndocker run -p 8080:8080 dog830228/mcp_weather_server:0.5.0 --mode sse\n```\n\n### Available Docker Images\n\n- **Latest**: `dog830228/mcp_weather_server:latest`\n- **Versioned**: `dog830228/mcp_weather_server:` (e.g., `0.5.0`)\n\nImages are automatically built and published when new versions are released.\n\n### Building from Source\n\nIf you want to build the Docker image yourself:\n\n#### Standard Build\n```bash\n# Build\ndocker build -t mcp-weather-server:sse .\n\n# Run (port will be read from PORT env var, defaults to 8081)\ndocker run -p 8081:8081 mcp-weather-server:sse\n\n# Run with custom port\ndocker run -p 8080:8080 mcp-weather-server:local --mode sse\n```\n\n#### Streamable HTTP Build\n```bash\n# Build using streamable-http Dockerfile\ndocker build -f Dockerfile.streamable-http -t mcp-weather-server:streamable-http .\n\n# Run in stateful mode\ndocker run -p 8080:8080 mcp-weather-server:streamable-http\n\n# Run in stateless mode\ndocker run -p 8080:8080 -e STATELESS=true mcp-weather-server:streamable-http\n```\n\n## Development\n\n### Project Structure\n\n```\nmcp_weather_server/\n├── src/\n│ └── mcp_weather_server/\n│ ├── __init__.py\n│ ├── __main__.py # Main MCP server entry point\n│ ├── server.py # Unified server (stdio, SSE, streamable-http)\n│ ├── utils.py # Utility functions\n│ └── tools/ # Tool implementations\n│ ├── __init__.py\n│ ├── toolhandler.py # Base tool handler\n│ ├── tools_weather.py # Weather-related tools\n│ ├── tools_time.py # Time-related tools\n│ ├── tools_air_quality.py # Air quality tools\n│ ├── weather_service.py # Weather API service\n│ └── air_quality_service.py # Air quality API service\n├── tests/\n├── Dockerfile # Docker configuration for SSE mode\n├── Dockerfile.streamable-http # Docker configuration for streamable-http mode\n├── pyproject.toml\n├── requirements.txt\n└── README.md\n```\n\n### Running for Development\n\n#### Standard MCP Mode (stdio)\n```bash\n# From project root\npython -m mcp_weather_server\n\n# Or with PYTHONPATH\nexport PYTHONPATH=\"/path/to/mcp_weather_server/src\"\npython -m mcp_weather_server\n```\n\n#### SSE Server Mode\n```bash\n# From project root\npython -m mcp_weather_server --mode sse --host 0.0.0.0 --port 8080\n\n# With custom host/port\npython -m mcp_weather_server --mode sse --host localhost --port 3000\n```\n\n#### Streamable HTTP Mode\n```bash\n# Stateful mode (default)\npython -m mcp_weather_server --mode streamable-http --host 0.0.0.0 --port 8080\n\n# With debug logging\npython -m mcp_weather_server --mode streamable-http --debug\n```\n\n### Adding New Tools\n\nTo add new weather or time-related tools:\n\n1. Create a new tool handler in the appropriate file under `tools/`\n2. Inherit from the `ToolHandler` base class\n3. Implement the required methods (`get_name`, `get_description`, `call`)\n4. Register the tool in `server.py`\n\n## Dependencies\n\n### Core Dependencies\n- `mcp>=1.0.0` - Model Context Protocol implementation\n- `httpx>=0.28.1` - HTTP client for API requests\n- `python-dateutil>=2.8.2` - Date/time parsing utilities\n\n### SSE Server Dependencies\n- `starlette` - ASGI web framework\n- `uvicorn` - ASGI server\n\n### Development Dependencies\n- `pytest` - Testing framework\n\n## API Data Sources\n\nThis server uses free and open-source APIs:\n\n### Weather Data: [Open-Meteo Weather API](https://open-meteo.com/)\n- Free and open-source\n- No API key required\n- Provides accurate weather forecasts\n- Supports global locations\n- Historical and current weather data\n- Comprehensive metrics (wind, precipitation, UV, visibility)\n\n### Air Quality Data:\n- Free and open-source\n- No API key required\n- Real-time air quality data\n- Multiple pollutant measurements (PM2.5, PM10, O3, NO2, CO, SO2)\n- Global coverage\n- Health-based air quality indices\n\n## Troubleshooting\n\n### Common Issues\n\n**1. City not found**\n- Ensure city names are in English\n- Try using the full city name or include country (e.g., \"Paris, France\")\n- Check spelling of city names\n\n**2. HTTP Server not accessible (SSE or Streamable HTTP)**\n- Verify the server is running with the correct mode:\n - SSE: `python -m mcp_weather_server --mode sse`\n - Streamable HTTP: `python -m mcp_weather_server --mode streamable-http`\n- Check firewall settings for the specified port\n- Ensure all dependencies are installed: `pip install starlette uvicorn`\n- Verify the correct endpoint:\n - SSE: `http://localhost:8080/sse` and `http://localhost:8080/messages/`\n - Streamable HTTP: `http://localhost:8080/mcp`\n\n**3. MCP Client connection issues**\n- Verify Python path in MCP client configuration\n- Check that `mcp_weather_server` package is installed\n- Ensure Python environment has required dependencies\n\n**4. Date format errors**\n- Use ISO 8601 format for dates: YYYY-MM-DD\n- Ensure start_date is before end_date\n- Check that dates are not too far in the future\n\n### Error Responses\n\nThe server returns structured error messages:\n\n```json\n{\n \"error\": \"Could not retrieve coordinates for InvalidCity.\"\n}\n```\n\n\n\n\n",
"bytes": 22167,
"sha": "60162db0a92d506d0b7ee155f69be7d10af53ae2d07908bee846c2cd6b95b2a2",
"repo_slug": "isdaniel/mcp_weather_server",
"fonte": "repo",
"truncated": false,
"api": "https://agentalog.com/api/listings/mcp_io_github_isdaniel_mcp_weather_server_f47ee2c5/readme"
}