MCP Weather 服务深度实战与 Cursor 集成白皮书

在 AI 驱动的应用开发中，实时天气数据的获取是旅行规划、户外活动安排、农业气象监测等场景的核心需求。MCP Weather 服务基于 Model Context Protocol (MCP) 标准构建，通过简洁的异步 HTTP 请求，为支持 MCP 协议的 AI 助手（如 Claude Desktop、Cursor）提供美国国家气象局 (NWS) 的实时天气预警和预报数据。本白皮书将深入剖析其架构、集成方式及生产部署要点，助你快速构建智能天气查询能力。

适用场景与技术亮点

MCP Weather 服务专为需要实时、精准天气数据的 AI 应用而设计。它最适合与支持 MCP 协议的 AI 助手协同工作，例如 Claude Desktop、Cursor 等。通过自然语言交互，用户可以直接查询特定美国州的天气预警或指定经纬度的天气预报，而无需手动调用 API。

技术亮点：

极简集成：基于官方 MCP SDK，安装和配置仅需数分钟。
实时数据：直接对接 NWS API，确保数据时效性。
异步架构：使用 httpx 异步 HTTP 客户端，避免阻塞 AI 助手的响应流程。
标准化接口：遵循 MCP 协议，可无缝接入任何 MCP 兼容的宿主环境。

架构优势与同类方案对比

MCP Weather 服务在功能丰富度、部署复杂度、性能等方面与同类方案存在显著差异。以下表格对比了其与常见天气数据集成方案的核心维度：

对比维度	MCP Weather 服务	自定义 REST API 集成	第三方天气 SDK
功能丰富度	仅天气预警和预报	完全可控，可扩展	通常包含历史数据、空气质量等
数据源依赖	美国国家气象局 (NWS)	任意 API	特定供应商（如 OpenWeatherMap）
部署复杂度	低（需 Python 环境和 uv 工具）	高（需自行搭建服务端）	中（需集成 SDK 并处理认证）
性能	异步 HTTP 请求，低延迟	取决于实现	通常有缓存和优化
扩展性	可添加更多工具函数	极高	受限于 SDK 功能
MCP 协议支持	原生支持	需自行实现	通常不支持

独特卖点：MCP Weather 服务的最大优势在于其与 MCP 生态的原生兼容性。开发者无需编写复杂的集成代码，只需通过 JSON 配置即可让 AI 助手直接调用天气工具，极大降低了开发门槛。

安装与核心启动命令

MCP Weather 服务依赖 Python 3.10+ 和 uv 工具。以下是完整的安装与启动命令：

bash
# 1. 创建项目目录并初始化虚拟环境
uv init weather && cd weather && uv venv && source .venv/bin/activate

# 2. 安装依赖（包含 MCP CLI 和 httpx）
uv add "mcp[cli]" httpx

# 3. 创建天气服务脚本
touch weather.py

注意：weather.py 文件需包含 MCP 服务器定义和工具函数。官方示例代码可从 MCP 文档↗ 获取。

启动参数对照表格

MCP Weather 服务通过工具参数接收用户输入。以下表格详细说明了各参数：

参数名	是否必填	默认值	作用解释
`state`	是	无	两位字母的美国州代码（如 CA, NY），用于查询天气预警
`latitude`	是	无	查询预报的纬度坐标（范围：-90 到 90）
`longitude`	是	无	查询预报的经度坐标（范围：-180 到 180）

示例：查询加利福尼亚州的天气预警：state=CA；查询纽约市（纬度 40.7128，经度 -74.0060）的天气预报：latitude=40.7128&longitude=-74.0060。

Claude Desktop 与 Cursor 集成配置

要将 MCP Weather 服务集成到 Claude Desktop 或 Cursor 中，需在宿主应用的配置文件中添加 mcpServers 配置。以下为标准的 JSON 配置模板：

json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
        "run",
        "weather.py"
      ]
    }
  }
}

配置步骤：

Claude Desktop：打开 claude_desktop_config.json（通常位于 ~/Library/Application Support/Claude/ 或 %APPDATA%\Claude\），将上述 JSON 添加到 mcpServers 对象中。
Cursor：打开 Cursor 设置，找到 MCP 服务器配置部分，添加新的服务器条目，将 command 和 args 填入对应字段。

注意：--directory 后的路径必须为 weather 目录的绝对路径。建议使用 pwd 命令获取当前路径，并确保路径中无空格或特殊字符。

生产环境部署建议与安全限制

生产环境部署 MCP Weather 服务需考虑以下关键限制与优化建议：

安全限制：

地域限制：仅支持美国地区天气数据，无法用于其他国家。
API 依赖：依赖 NWS API，可能受速率限制（默认 30 秒超时）或服务中断影响。
无认证机制：直接暴露 API 调用，无内置认证。
无缓存策略：每次请求都调用外部 API，增加延迟和负载。
无错误重试机制：网络故障时直接返回 None。
日志输出限制：STDIO 模式下不能使用 print 到 stdout，需使用 logging 模块写入文件。

生产部署建议：

进程管理：使用 pm2 或 supervisor 确保服务持续运行。
错误处理：添加重试逻辑（如指数退避）和超时控制。
缓存层：引入 Redis 或内存缓存，减少 API 调用频率。
日志管理：配置日志轮转，避免磁盘占满。
环境变量：使用 .env 文件管理敏感信息（如 API 密钥）。
传输协议：考虑使用 HTTP 传输而非 STDIO，便于监控和扩展。

常见报错与故障排除

以下是 MCP Weather 服务部署和运行中常见的错误及解决方案：

错误 1：`uv: command not found`

原因：uv 工具未安装或未添加到 PATH。 解决方案：

bash
# 安装 uv 工具
curl -LsSf https://astral.sh/uv/install.sh | sh
# 重启终端或重新加载 shell 配置
source ~/.bashrc  # 或 source ~/.zshrc

错误 2：`ModuleNotFoundError: No module named 'mcp'`

原因：未在虚拟环境中安装依赖。 解决方案：

bash
# 确保在虚拟环境中
source .venv/bin/activate
# 安装依赖
uv add "mcp[cli]" httpx

错误 3：`Connection timeout when calling NWS API`

原因：网络无法访问 api.weather.gov 或 API 响应超时。 解决方案：

检查网络连接：curl -I https://api.weather.gov
增加超时时间（在 weather.py 中修改 httpx 的 timeout 参数）
实现重试逻辑（如使用 tenacity 库）

错误 4：`Invalid state code or coordinates`

原因：参数格式错误或超出范围。 解决方案：

state 必须为两位字母的美国州代码（如 CA, NY, TX）
latitude 范围：-90 到 90
longitude 范围：-180 到 180

常见问题解答 (FAQ)

Q: 如何将此 MCP 服务器部署到生产环境？

A: 生产部署建议：1. 使用进程管理器（如 pm2 或 supervisor）确保服务持续运行。2. 添加错误处理和重试机制。3. 实现缓存层（如 Redis）减少 API 调用。4. 设置日志记录到文件而非 stdout。5. 使用环境变量管理敏感信息。6. 考虑使用 HTTP 传输而非 STDIO 以便于监控和扩展。

Q: 能否扩展此服务器以支持其他国家天气数据？

A: 可以。需要添加新的数据源 API（如 OpenWeatherMap、Weatherstack 等），并创建相应的工具函数。注意不同 API 的认证方式和数据格式差异。建议使用适配器模式封装不同数据源，保持接口一致性。

Q: 如何测试此 MCP 服务器而不使用 Claude Desktop？

A: 可以使用 MCP Inspector 工具进行测试：运行 npx @modelcontextprotocol/inspector uv --directory /path/to/weather run weather.py。或者编写自定义 MCP 客户端，使用 mcp 库的 Client 类连接服务器并调用工具。