Weather MCP Server

Weather MCP 服务

mcp-name: io.github.isdaniel/mcp_weather_server

一个使用 Open-Meteo API 提供天气信息的 Model Context Protocol (MCP) 服务。此服务支持多种传输模式：标准 stdio、HTTP Server-Sent Events (SSE)，以及适用于 Web 集成的新版 Streamable HTTP 协议。

功能

天气与空气质量

• 获取包含全面指标的当前天气信息：
  • 温度、湿度、露点
  • 风速、风向和阵风
  • 降水（雨/雪）及其概率
  • 大气压力和云量
  • UV 指数和能见度
  • “体感”温度
  • 日出和日落时间（所在地的当地时间）
• 获取指定日期范围内的天气数据，包括逐小时详情和每日日出/日落时间
• 获取空气质量信息，包括：
  • PM2.5 和 PM10 颗粒物
  • 臭氧、二氧化氮、一氧化碳
  • 二氧化硫、氨、粉尘
  • 气溶胶光学厚度
  • 健康提示和建议

时间与时区

• 获取任意时区的当前日期/时间
• 转换不同时区之间的时间
• 获取时区信息

传输模式

• 多种传输模式：
  • stdio - 面向桌面客户端的标准 MCP（Claude Desktop 等）
  • SSE - 面向 Web 应用的 Server-Sent Events
  • streamable-http - 具有有状态/无状态选项的现代 MCP Streamable HTTP 协议
• 通过 Starlette 集成提供 RESTful API 端点

安装

通过 Smithery 安装

要通过 Smithery 自动安装 Weather MCP 服务：

npx -y @smithery/cli install @isdaniel/mcp_weather_server

标准安装（适用于 Claude Desktop 等 MCP 客户端）

此软件包可以使用 pip 安装：

pip install mcp_weather_server

MCP 客户端的手动配置

此服务旨在通过将配置添加到 cline_mcp_settings.json 文件中进行手动安装。

1. 在 cline_mcp_settings.json 文件的 mcpServers 对象中添加以下条目：

{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": [
        "-m",
        "mcp_weather_server"
      ],
      "disabled": false,
      "autoApprove": []
    }
  }
}

2. 保存 cline_mcp_settings.json 文件。

HTTP 服务安装（适用于 Web 应用）

要支持 HTTP SSE 或 Streamable HTTP，需要安装额外的依赖项：

pip install mcp_weather_server starlette uvicorn

服务模式

此 MCP 服务在一个统一服务中支持 stdio、SSE 和 streamable-http 模式：

模式对比

功能	stdio	SSE	streamable-http
使用场景	桌面 MCP 客户端	Web 应用（旧版）	Web 应用（现代）
协议	标准 I/O 流	Server-Sent Events	MCP Streamable HTTP
会话管理	不适用	有状态	有状态或无状态
端点	不适用	/sse、/messages/	/mcp（单一端点）
最适用	Claude Desktop、Cline	基于浏览器的应用	现代 Web 应用、API
状态选项	不适用	仅有状态	有状态或无状态

1. 标准 MCP 模式（默认）

标准模式通过 stdio 通信，并兼容 Claude Desktop 等 MCP 客户端。

# Default mode (stdio)
python -m mcp_weather_server

# Explicitly specify stdio mode
python -m mcp_weather_server.server --mode stdio

2. HTTP SSE 模式（Web 应用）

SSE 模式会运行一个 HTTP 服务，通过 Server-Sent Events 提供 MCP 功能，使其可供 Web 应用访问。

# Start SSE server on default host/port (0.0.0.0:8080)
python -m mcp_weather_server --mode sse

# Specify custom host and port
python -m mcp_weather_server --mode sse --host localhost --port 3000

# Enable debug mode
python -m mcp_weather_server --mode sse --debug

SSE 端点：

• GET /sse - 用于 MCP 通信的 SSE 端点
• POST /messages/ - 用于发送 MCP 请求的消息端点

3. Streamable HTTP 模式（现代 MCP 协议）

streamable-http 模式通过单个 /mcp 端点实现新的 MCP Streamable HTTP 协议。此模式同时支持有状态（默认）和无状态操作。

# Start streamable HTTP server on default host/port (0.0.0.0:8080)
python -m mcp_weather_server --mode streamable-http

# Specify custom host and port
python -m mcp_weather_server --mode streamable-http --host localhost --port 3000

# Enable stateless mode (creates fresh transport per request, no session tracking)
python -m mcp_weather_server --mode streamable-http --stateless

# Enable debug mode
python -m mcp_weather_server --mode streamable-http --debug

Streamable HTTP 功能：

• 有状态模式（默认）：使用会话 ID 在多个请求间维护会话状态
• 无状态模式：每个请求都会创建新的传输，不跟踪会话
• 单一端点：所有 MCP 通信都通过 /mcp 进行
• 现代协议：实现最新的 MCP Streamable HTTP 规范

Streamable HTTP 端点：

• POST /mcp - 用于所有 MCP 通信的单一端点（initialize、tools/list、tools/call 等）

命令行选项：

--mode {stdio,sse,streamable-http}  Server mode: stdio (default), sse, or streamable-http
--host HOST                          Host to bind to (HTTP modes only, default: 0.0.0.0)
--port PORT                          Port to listen on (HTTP modes only, default: 8080)
--stateless                          Run in stateless mode (streamable-http only)
--debug                              Enable debug mode

SSE 使用示例：

// Connect to SSE endpoint
const eventSource = new EventSource('http://localhost:8080/sse');

// Send MCP tool request
fetch('http://localhost:8080/messages/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'tool_call',
    tool: 'get_weather',
    arguments: { city: 'Tokyo' }
  })
});

Streamable HTTP 使用示例：

// Initialize session and call tool using Streamable HTTP protocol
async function callWeatherTool() {
  const response = await fetch('http://localhost:8080/mcp', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      jsonrpc: '2.0',
      method: 'tools/call',
      params: {
        name: 'get_current_weather',
        arguments: { city: 'Tokyo' }
      },
      id: 1
    })
  });

  const result = await response.json();
  console.log(result);
}

配置

此服务不需要 API 密钥。它使用免费的开源 Open-Meteo API。

用法

此服务提供了多种天气和时间相关操作的工具：

可用工具

天气工具

1. get_current_weather - 获取某个城市当前天气的综合指标
2. get_weather_by_datetime_range - 获取指定日期范围内的天气数据及逐小时详情
3. get_weather_details - 以结构化 JSON 数据的形式获取详细天气信息

空气质量工具

4. get_air_quality - 获取空气质量信息，包括污染物水平和健康建议
5. get_air_quality_details - 以结构化 JSON 的形式获取详细空气质量数据

时间与时区工具

6. get_current_datetime - 获取任意时区的当前时间
7. get_timezone_info - 获取时区信息
8. convert_time - 在不同时区之间转换时间

工具详情

get_current_weather

获取指定城市当前天气的综合信息及增强指标。

参数：

• city（字符串，必填）：城市名称（仅限英文名称）

**返回：**详细天气数据，包括：

• 温度和体感温度
• 湿度、露点
• 风速、风向（以罗盘方向表示）和阵风
• 降水详情（雨/雪）及概率
• 大气压力和云量
• 带有警告等级的 UV 指数
• 能见度

响应示例：

The weather in Tokyo is Mainly clear with a temperature of 22.5°C (feels like 21.0°C),
relative humidity at 65%, and dew point at 15.5°C. Wind is blowing from the NE at 12.5 km/h
with gusts up to 18.5 km/h. Atmospheric pressure is 1013.2 hPa with 25% cloud cover.
UV index is 5.5 (Moderate). Visibility is 10.0 km.

get_weather_by_datetime_range

获取指定城市在开始日期和结束日期之间的逐小时天气信息及综合指标。

参数：

• city（字符串，必填）：城市名称（仅限英文名称）
• start_date（字符串，必填）：开始日期，格式为 YYYY-MM-DD（ISO 8601）
• end_date（字符串，必填）：结束日期，格式为 YYYY-MM-DD（ISO 8601）

**返回：**综合天气分析，包括：

• 包含所有增强指标的逐小时天气数据
• 温度趋势（最高、最低和平均值）
• 降水模式和概率
• 风况评估
• UV 指数趋势
• 天气预警和建议

响应示例：

[Analysis of weather trends over 2024-01-01 to 2024-01-07]
- Temperature ranges from 5°C to 15°C
- Precipitation expected on Jan 3rd and 5th (60% probability)
- Wind speeds averaging 15 km/h from SW direction
- UV index moderate (3-5) throughout the period
- Recommendation: Umbrella needed for midweek

get_weather_details

以结构化 JSON 数据的形式获取指定城市的详细天气信息，供程序使用。

参数：

• city（字符串，必填）：城市名称（仅限英文名称）

**返回：**包含所有天气指标的原始 JSON 数据，适用于处理和分析

get_air_quality

获取指定城市当前的空气质量信息，包括污染物水平和健康建议。

参数：

• city（string，必填）：城市名称（仅支持英文名称）
• variables（array，可选）：要获取的特定污染物。选项：
  • pm10 - 颗粒物 ≤10μm
  • pm2_5 - 颗粒物 ≤2.5μm
  • carbon_monoxide - CO 水平
  • nitrogen_dioxide - NO2 水平
  • ozone - O3 水平
  • sulphur_dioxide - SO2 水平
  • ammonia - NH3 水平
  • dust - 粉尘颗粒水平
  • aerosol_optical_depth - 大气浑浊度

**返回：**全面的空气质量报告，包括：

• 当前污染物水平及单位
• 空气质量分类（良好/中等/不健康/危险）
• 面向一般人群的健康建议
• 针对敏感人群的特别警告
• 与 WHO 和 EPA 标准的比较

响应示例：

Air quality in Beijing (lat: 39.90, lon: 116.41):
PM2.5: 45.3 μg/m³ (Unhealthy for Sensitive Groups)
PM10: 89.2 μg/m³ (Moderate)
Ozone (O3): 52.1 μg/m³
Nitrogen Dioxide (NO2): 38.5 μg/m³
Carbon Monoxide (CO): 420.0 μg/m³

Health Advice: Sensitive groups (children, elderly, people with respiratory conditions)
should limit outdoor activities.

get_air_quality_details

以结构化 JSON 数据的形式获取详细空气质量信息，用于程序化分析。

参数：

• city（string，必填）：城市名称（仅支持英文名称）
• variables（array，可选）：要获取的特定污染物（选项与 get_air_quality 相同）

**返回：**包含完整空气质量指标和每小时数据的原始 JSON 数据

get_current_datetime

获取指定时区的当前时间。

参数：

• timezone_name（string，必填）：IANA 时区名称（例如：'America/New_York'、'Europe/London'）。如果未提供时区，请使用 UTC。

**返回：**指定时区的当前日期和时间

示例：

{
  "timezone": "America/New_York",
  "current_time": "2024-01-15T14:30:00-05:00",
  "utc_time": "2024-01-15T19:30:00Z"
}

get_timezone_info

获取特定时区的信息。

参数：

• timezone_name（string，必填）：IANA 时区名称

**返回：**时区详情，包括偏移量和夏令时信息

convert_time

将时间从一个时区转换到另一个时区。

参数：

• time_str（string，必填）：要转换的时间（ISO 格式）
• from_timezone（string，必填）：源时区
• to_timezone（string，必填）：目标时区

**返回：**目标时区的转换后时间

MCP 客户端使用示例

与 Claude Desktop 或 MCP 客户端配合使用

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_current_weather</tool_name>
<arguments>
{
  "city": "Tokyo"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_weather_by_datetime_range</tool_name>
<arguments>
{
  "city": "Paris",
  "start_date": "2024-01-01",
  "end_date": "2024-01-07"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_current_datetime</tool_name>
<arguments>
{
  "timezone_name": "Europe/Paris"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_air_quality</tool_name>
<arguments>
{
  "city": "Beijing"
}
</arguments>
</use_mcp_tool>

<use_mcp_tool>
<server_name>weather</server_name>
<tool_name>get_air_quality</tool_name>
<arguments>
{
  "city": "Los Angeles",
  "variables": ["pm2_5", "pm10", "ozone"]
}
</arguments>
</use_mcp_tool>

Web 集成（SSE 模式）

在 SSE 模式下运行时，可以将天气服务集成到 Web 应用中：

HTML/JavaScript 示例

<!DOCTYPE html>
<html>
<head>
    <title>Weather MCP Client</title>
</head>
<body>
    <div id="weather-data"></div>
    <script>
        // Connect to SSE endpoint
        const eventSource = new EventSource('http://localhost:8080/sse');

        eventSource.onmessage = function(event) {
            const data = JSON.parse(event.data);
            document.getElementById('weather-data').innerHTML = JSON.stringify(data, null, 2);
        };

        // Function to get weather
        async function getWeather(city) {
            const response = await fetch('http://localhost:8080/messages/', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    jsonrpc: '2.0',
                    method: 'tools/call',
                    params: {
                        name: 'get_current_weather',
                        arguments: { city: city }
                    },
                    id: 1
                })
            });
        }

        // Example: Get weather for Tokyo
        getWeather('Tokyo');

        // Example: Get air quality
        async function getAirQuality(city) {
            const response = await fetch('http://localhost:8080/messages/', {
                method: 'POST',
                headers: { 'Content-Type': 'application/json' },
                body: JSON.stringify({
                    jsonrpc: '2.0',
                    method: 'tools/call',
                    params: {
                        name: 'get_air_quality',
                        arguments: { city: city }
                    },
                    id: 2
                })
            });
        }

        getAirQuality('Beijing');
    </script>
</body>
</html>

Docker 部署

本项目以 Docker 镜像形式发布在 Docker Hub 上，并提供了便于部署的配置。

使用 Docker Hub 快速开始

直接从 Docker Hub 拉取并运行最新镜像：

# Pull the latest image
docker pull dog830228/mcp_weather_server:latest

# Run in stdio mode (default)
docker run dog830228/mcp_weather_server:latest

# Run in SSE mode on port 8080
docker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode sse

# Run in streamable-http mode on port 8080
docker run -p 8080:8080 dog830228/mcp_weather_server:latest --mode streamable-http

# Pull a specific version
docker pull dog830228/mcp_weather_server:0.5.0
docker run -p 8080:8080 dog830228/mcp_weather_server:0.5.0 --mode sse

可用的 Docker 镜像

• 最新版本：dog830228/mcp_weather_server:latest
• 指定版本：dog830228/mcp_weather_server:<version>（例如，0.5.0）

发布新版本时会自动构建并发布镜像。

从源代码构建

如果要自行构建 Docker 镜像：

标准构建

# Build
docker build -t mcp-weather-server:sse .

# Run (port will be read from PORT env var, defaults to 8081)
docker run -p 8081:8081 mcp-weather-server:sse

# Run with custom port
docker run -p 8080:8080 mcp-weather-server:local --mode sse

Streamable HTTP 构建

# Build using streamable-http Dockerfile
docker build -f Dockerfile.streamable-http -t mcp-weather-server:streamable-http .

# Run in stateful mode
docker run -p 8080:8080 mcp-weather-server:streamable-http

# Run in stateless mode
docker run -p 8080:8080 -e STATELESS=true mcp-weather-server:streamable-http

开发

项目结构

mcp_weather_server/
├── src/
│   └── mcp_weather_server/
│       ├── __init__.py
│       ├── __main__.py          # Main MCP server entry point
│       ├── server.py            # Unified server (stdio, SSE, streamable-http)
│       ├── utils.py             # Utility functions
│       └── tools/               # Tool implementations
│           ├── __init__.py
│           ├── toolhandler.py   # Base tool handler
│           ├── tools_weather.py # Weather-related tools
│           ├── tools_time.py    # Time-related tools
│           ├── tools_air_quality.py # Air quality tools
│           ├── weather_service.py   # Weather API service
│           └── air_quality_service.py # Air quality API service
├── tests/
├── Dockerfile                   # Docker configuration for SSE mode
├── Dockerfile.streamable-http   # Docker configuration for streamable-http mode
├── pyproject.toml
├── requirements.txt
└── README.md

运行开发环境

标准 MCP 模式（stdio）

# From project root
python -m mcp_weather_server

# Or with PYTHONPATH
export PYTHONPATH="/path/to/mcp_weather_server/src"
python -m mcp_weather_server

SSE 服务模式

# From project root
python -m mcp_weather_server --mode sse --host 0.0.0.0 --port 8080

# With custom host/port
python -m mcp_weather_server --mode sse --host localhost --port 3000

Streamable HTTP 模式

# Stateful mode (default)
python -m mcp_weather_server --mode streamable-http --host 0.0.0.0 --port 8080

# With debug logging
python -m mcp_weather_server --mode streamable-http --debug

添加新工具

添加新的天气或时间相关工具：

1. 在 tools/ 下的相应文件中创建新的工具处理器
2. 继承 ToolHandler 基类
3. 实现必需的方法（get_name、get_description、call）
4. 在 server.py 中注册该工具

依赖项

核心依赖项

• mcp>=1.0.0 - Model Context Protocol 实现
• httpx>=0.28.1 - 用于 API 请求的 HTTP 客户端
• python-dateutil>=2.8.2 - 日期/时间解析工具

SSE 服务依赖项

• starlette - ASGI Web 框架
• uvicorn - ASGI 服务

开发依赖项

• pytest - 测试框架

API 数据源

此服务使用免费的开源 API：

天气数据：Open-Meteo Weather API

• 免费且开源
• 无需 API 密钥
• 提供准确的天气预报
• 支持全球各地
• 提供历史和当前天气数据
• 涵盖多种指标（风、降水、紫外线、能见度）

空气质量数据：

• 免费且开源
• 无需 API 密钥
• 实时空气质量数据
• 多种污染物测量数据（PM2.5、PM10、O3、NO2、CO、SO2）
• 覆盖全球
• 基于健康标准的空气质量指数

故障排除

常见问题

1. 未找到城市

• 确保城市名称使用英文
• 尝试使用完整城市名称，或注明国家/地区（例如，“Paris, France”）
• 检查城市名称的拼写

2. 无法访问 HTTP 服务（SSE 或 Streamable HTTP）

• 确认服务以正确模式运行：
  • SSE：python -m mcp_weather_server --mode sse
  • Streamable HTTP：python -m mcp_weather_server --mode streamable-http
• 检查指定端口的防火墙设置
• 确保已安装所有依赖项：pip install starlette uvicorn
• 确认端点正确：
  • SSE：http://localhost:8080/sse 和 http://localhost:8080/messages/
  • Streamable HTTP：http://localhost:8080/mcp

3. MCP 客户端连接问题

• 检查 MCP 客户端配置中的 Python 路径
• 确认已安装 mcp_weather_server 包
• 确保 Python 环境中包含所需依赖项

4. 日期格式错误

• 日期请使用 ISO 8601 格式：YYYY-MM-DD
• 确保 start_date 早于 end_date
• 检查日期是否距离未来太远

错误响应

服务会返回结构化错误消息：

{
  "error": "Could not retrieve coordinates for InvalidCity."
}