JinDaGe - weather-mcp-server MCP Details

article

README

🚀 天气MCP服务器

这是一个模型上下文协议（MCP）服务器，借助WeatherAPI服务提供天气信息。该服务器允许AI助手通过标准输入输出（stdio）通信获取当前天气、天气预报，并搜索地点。

🚀 快速开始

本服务器可让AI助手借助标准输入输出通信获取当前天气、天气预报并搜索地点。你可以按照以下步骤进行安装和配置。

✨ 主要特性

当前天气：获取任意地点的实时天气状况
天气预报：获取长达14天的天气预报
地点搜索：查找并验证地点名称
空气质量数据：可选的空气质量信息
调试日志：全面的日志记录，便于故障排查
标准输入输出通信：通过标准输入/输出进行直接的MCP协议通信

📦 安装指南

选项1：通过Smithery（推荐）

通过 Smithery MCP注册表自动安装：

npx -y @smithery/cli install weather-mcp-server --client claude

或者用于其他MCP客户端：

npx -y @smithery/cli install weather-mcp-server

这将自动完成以下操作：

安装天气MCP服务器
将其添加到你的MCP客户端配置中
提示你输入WeatherAPI密钥

选项2：手动安装

克隆或下载此仓库
获取WeatherAPI密钥：
- 在 https://www.weatherapi.com 注册
- 从仪表盘获取免费的API密钥
- ⚠️ 重要提示
请确保你的API密钥安全，切勿将其提交到版本控制系统。
安装依赖项：

uv sync

💻 使用示例

运行服务器

直接执行

WEATHER_API_KEY=your_api_key uv run server.py

启用调试日志

DEBUG=true WEATHER_API_KEY=your_api_key uv run server.py

通过MCP客户端

当你的MCP客户端（如mcphost或Claude Desktop）连接到服务器时，服务器将自动启动。

可用工具

1. weather_current

获取某个地点的当前天气状况。参数：

q（必需）：地点查询（城市名称、坐标、邮政编码）
aqi（可选）：是否包含空气质量数据（“yes” 或 “no”，默认：“no”）示例：

{
  "name": "weather_current",
  "arguments": {
    "q": "New York, NY",
    "aqi": "yes"
  }
}

2. weather_forecast

获取1 - 14天的天气预报。参数：

q（必需）：地点查询
days（可选）：预报天数（1 - 14，默认：1）示例：

{
  "name": "weather_forecast",
  "arguments": {
    "q": "London, UK",
    "days": 7
  }
}

3. weather_search

搜索与查询匹配的地点。参数：

q（必需）：搜索查询示例：

{
  "name": "weather_search",
  "arguments": {
    "q": "Paris"
  }
}

地点查询格式

天气工具支持多种地点格式：

城市名称：“New York”、“London”
城市和州/国家：“New York, NY”、“London, UK”
坐标：“40.7128,-74.0060”
邮政编码：“10001”、“SW1A 1AA”
机场代码：“JFK”、“LHR”

📚 详细文档

配置

环境变量

设置你的WeatherAPI密钥：

export WEATHER_API_KEY=your_api_key_here

可选 - 启用调试日志：

export DEBUG=true

MCP客户端配置

将此服务器添加到你的MCP客户端配置（例如 config.json）中：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "WEATHER_API_KEY": "your_api_key_here"
      }
    }
  }
}

启用调试日志，添加 DEBUG 环境变量：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/weather-mcp-server",
        "run",
        "server.py"
      ],
      "env": {
        "WEATHER_API_KEY": "your_api_key_here",
        "DEBUG": "true"
      }
    }
  }
}

测试

手动测试

使用JSON - RPC请求测试服务器：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | WEATHER_API_KEY=your_api_key uv run server.py

启用调试日志：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}' | DEBUG=true WEATHER_API_KEY=your_api_key uv run server.py

工具测试

测试天气工具：

echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"weather_current","arguments":{"q":"New York"}}}' | WEATHER_API_KEY=your_api_key uv run server.py

Docker支持

构建镜像

docker build -t weather-mcp-server .

使用Docker运行

docker run --rm -i -e WEATHER_API_KEY=your_api_key weather-mcp-server

调试模式

服务器支持可选的调试日志。设置 DEBUG 环境变量以启用详细日志记录。 日志级别：

INFO：基本服务器操作（默认）
DEBUG：详细的请求/响应信息、API调用（当 DEBUG=true 时）

错误处理

服务器能够优雅地处理常见错误：

无效的API密钥：返回带有指导的错误消息
未找到地点：建议替代搜索词
网络问题：提供重试建议
速率限制：指示何时超出限制

依赖项

httpx：用于API请求的HTTP客户端
asyncio：支持异步/等待
标准库：json、logging、sys、os

API限制

WeatherAPI免费套餐包括：

每月100万次调用
当前天气和3天天气预报
可升级以获取更长的预报和更高的限制

故障排除

常见问题

“No content response received”
- 检查API密钥是否正确设置
- 验证网络连接
- 查看调试日志以查找错误
“API key not provided”
- 设置 WEATHER_API_KEY 环境变量
- 检查MCP客户端配置
“Location not found”
- 尝试不同的地点格式
- 使用 weather_search 工具查找有效地点

调试输出

通过设置 DEBUG 环境变量启用详细日志记录：

DEBUG=true WEATHER_API_KEY=your_api_key uv run server.py 2>&1 | grep -E "(DEBUG|ERROR)"

架构

此服务器使用以下方式实现MCP协议：

标准输入输出通信：通过标准输入/输出进行直接的JSON - RPC通信
异步事件循环：非阻塞请求处理
手动JSON - RPC：自定义实现以实现精确控制
WeatherAPI集成：带有错误处理的RESTful API调用

贡献

分叉仓库
创建功能分支
进行更改
彻底测试
提交拉取请求

许可证

本项目采用MIT许可证 - 详情请参阅 LICENSE 文件。

支持

WeatherAPI文档：https://www.weatherapi.com/docs/
MCP规范：https://spec.modelcontextprotocol.io/
问题反馈：在仓库的问题跟踪器中报告错误和功能请求

最后更新时间：2025年7月12日