MCP Weather Server (mcp-weather-server)

](https://smithery.ai/server/@isdaniel/mcp_weather_server) ](https://pypi.org/project/mcp-weather-server/) ](https://pypi.org/project/mcp-weather-server/) ](https://pepy.tech/projects/mcp-weather-server) ](https://hub.docker.com/r/dog830228/mcp_weather_server)

气象MCP服务器

mcp名称：io.github.isdaniel/mcp_weather_server

一种模型上下文协议（MCP）服务器，使用Open-Meteo API提供天气信息。此服务器支持多种传输模式：标准stdio、HTTP服务器发送事件（SSE）和用于基于web的集成的新Streamable HTTP协议。

特性

天气和空气质量

• 通过综合指标获取当前天气信息：

- 温度、湿度、露点 - 风速、风向和阵风 - 降水（雨/雪）和概率 - 大气压力和云量 - 紫外线指数和能见度 - “感觉像”温度

• 获取日期范围内的天气数据，包括每小时的详细信息
• 获取空气质量信息，包括：

- PM2.5和PM10颗粒物 - 臭氧、二氧化氮、一氧化碳 - 二氧化硫、氨、粉尘 - 气溶胶光学厚度 - 健康咨询和建议

时间和时区

• 获取任何时区的当前日期/时间
• 在时区之间转换时间
• 获取时区信息

运输方式

• 多种运输方式：

- 标准 -桌面客户端的标准MCP（Claude desktop等） - 上海证券交易所 -web应用程序的服务器发送事件 - 可流式传输http -具有有状态/无状态选项的现代MCP流式HTTP协议

• 通过Starlette集成实现RESTful API端点

安装

通过Smithery安装

通过以下方式自动安装天气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. 将以下条目添加到 mcpServers 对象在你 cline_mcp_settings.json 文件：

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

1. 保存 cline_mcp_settings.json 文件。

HTTP服务器安装（用于web应用程序）

对于HTTP SSE或Streamable HTTP支持，您需要额外的依赖关系：

pip install mcp_weather_server starlette uvicorn

服务器模式

此MCP服务器支持 标准, 上海证券交易所，以及 可流式传输http 单个统一服务器中的模式：

模式比较

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服务器，该服务器通过服务器发送事件提供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.流式HTTP模式（现代MCP协议）

流式http模式实现了新的MCP流式http协议 /mcp 终点。此模式支持有状态（默认）和无状态操作。

# 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

流式HTTP功能：

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

可流式传输HTTP端点：

• POST /mcp -所有MCP通信的单一端点（初始化、工具/列表、工具/调用等）

命令行选项：

--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' }
  })
});

流式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数据的形式获取详细的天气信息

空气质量工具

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

时间和时区工具

1. get_current_datetime -获取任何时区的当前时间
2. get_timezone_info -获取时区信息
3. convert_time -在时区之间转换时间

工具详细信息

get_current_weather

使用增强的指标检索给定城市的全面当前天气信息。

参数：

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

退货： 详细的天气数据包括：

• 温度和“感觉”温度
• 湿度、露点
• 风速、风向（如指南针方向）和阵风
• 降水细节（雨/雪）和概率
• 大气压力和云量
• 带有警告级别的紫外线指数
• 能见度

示例响应：

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 （string，必填）：城市名称（仅限英文名称）
• start_date （字符串，必填）：开始日期，格式为YYYY-MM-DD（ISO 8601）
• end_date （字符串，必填）：结束日期，格式为YYYY-MM-DD（ISO 8601）

退货： 综合天气分析包括：

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

示例响应：

[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 （string，必填）：城市名称（仅限英文名称）

退货： 原始JSON数据，包含适合处理和分析的所有天气指标

get_air_quality

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

参数：

• city （string，必填）：城市名称（仅限英文名称）
• variables （数组，可选）：要检索的特定污染物。选项：

- pm10 -颗粒物≤10μm - pm2_5 -颗粒物≤2.5μm - carbon_monoxide -CO水平 - nitrogen_dioxide -NO2水平 - ozone -O3水平 - sulphur_dioxide -二氧化硫水平 - ammonia -NH3水平 - dust -灰尘颗粒水平 - aerosol_optical_depth -大气浑浊度

退货： 综合空气质量报告包括：

• 当前污染物水平（单位）
• 空气质量分类（良好/中等/不健康/危险）
• 针对普通人群的健康建议
• 针对敏感群体的具体警告
• 与世界卫生组织和环保局标准的比较

示例响应：

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 （数组，可选）：要检索的特定污染物（与 get_air_quality)

退货： 原始JSON数据，包含完整的空气质量指标和小时数据

get_current_datetime

检索指定时区的当前时间。

参数：

• timezone_name （字符串，必填）：IANA时区名称（例如，“美国/纽约”、“欧洲/伦敦”）。如果没有提供时区，请使用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 （字符串，必填）：IANA时区名称

退货： 时区详细信息，包括时差和夏令时信息

convert_time

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

参数：

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

退货： 目标时区转换时间

MCP客户端使用示例

与Claude Desktop或MCP客户端一起使用

weather
get_current_weather

{
  "city": "Tokyo"
}

weather
get_weather_by_datetime_range

{
  "city": "Paris",
  "start_date": "2024-01-01",
  "end_date": "2024-01-07"
}

weather
get_current_datetime

{
  "timezone_name": "Europe/Paris"
}

weather
get_air_quality

{
  "city": "Beijing"
}

weather
get_air_quality

{
  "city": "Los Angeles",
  "variables": ["pm2_5", "pm10", "ozone"]
}

Web集成（SSE模式）

在SSE模式下运行时，您可以将天气服务器与web应用程序集成：

HTML/JavaScript示例

    Weather MCP Client

    

    
        // 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');
    

Docker部署

该项目在Docker Hub上以Docker镜像的形式提供，并包含易于部署的配置。

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: （例如。， 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

流式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

流式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 -模型上下文协议实现
• httpx>=0.28.1 -API请求的HTTP客户端
• python-dateutil>=2.8.2 -日期/时间解析实用程序

SSE服务器依赖关系

• starlette -ASGI web框架
• uvicorn -ASGI服务器

开发依赖

• pytest -测试框架

API数据源

此服务器使用免费和开源API：

天气数据： 开放气象API

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

空气质量数据：

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

故障排除

常见问题

1.未找到城市

• 确保城市名称为英文
• 尝试使用完整的城市名称或包含国家（例如，“法国巴黎”）
• 检查城市名称的拼写

2.HTTP服务器不可访问（SSE或流式HTTP）

• 验证服务器是否以正确的模式运行：

- 上海证券交易所 python -m mcp_weather_server --mode sse - 流式HTTP： python -m mcp_weather_server --mode streamable-http

• 检查指定端口的防火墙设置
• 确保安装了所有依赖项： pip install starlette uvicorn
• 验证正确的端点：

- 上海证券交易所 http://localhost:8080/sse 和 http://localhost:8080/messages/ - 流式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."
}