Weather Forecast MCP Server

天气预报MCP服务器

生产就绪的MCP服务器，用于使用美国国家气象局API进行实时天气预报。

A. 模型上下文协议 （MCP）服务器，为Claude和其他人工智能应用程序提供安全、进程隔离的天气数据访问。使用Python、FastMCP构建，专为生产部署而设计。

特性

• ✅ 4个MCP工具: geocode_city, get_forecast, get_alerts, get_forecast_dashboard
• ✅ 2 MCP资源: weather://climate/normals/{location}/{month} 和 ui://weather/dashboard
• ✅ 进程隔离：作为具有作用域凭据的独立服务器运行
• ✅ stdio运输：使用Claude Desktop进行本地开发
• ✅ Docker就绪：具有安全强化功能的生产部署
• ✅ 预测不需要API密钥：使用免费的美国国家气象局API
• ✅ 可选气候正常值：美国国家海洋和大气管理局CDO集成 NOAA_API_TOKEN
• ✅ 异步/等待：非阻塞I/O，实现高效的请求处理
• ✅ MCP应用程序示例：直接从此Python服务器提供的交互式天气仪表板

快速开始

安装

选项1：使用紫外线（推荐）

安装 紫外线 如果你还没有：

curl -LsSf https://astral.sh/uv/install.sh | sh

克隆存储库

git clone https://github.com/slin-master/weather-forecast-mcp-server.git
cd weather-forecast-mcp-server

注意：通过uv运行时会自动安装依赖项。

选项2：使用pip

克隆存储库

git clone https://github.com/slin-master/weather-forecast-mcp-server.git
cd weather-forecast-mcp-server

安装依赖项

pip install -e .

本地测试

使用stdio传输启动MCP服务器：

使用紫外线（推荐）

uv run mcp run src/weather_forecast_mcp_server/server.py

或者用pip

mcp run src/weather_forecast_mcp_server/server.py

服务器现在正在运行，并通过stdio等待JSON-RPC连接。

MCP检验员测试

这 MCP检查员 提供了一个用于测试的web UI：

全局安装检查器

npm install -g @modelcontextprotocol/inspector

连接到您的服务器

npx @modelcontextprotocol/inspector uv run mcp run src/weather_forecast_mcp_server/server.py

打开http://localhost:5173致：

1. 连接到服务器
2. 探索可用工具
3. 使用示例输入调用测试工具

与Claude Desktop一起使用

添加到您的 ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/weather-forecast-mcp-server",
        "run",
        "mcp",
        "run",
        "src/weather_forecast_mcp_server/server.py"
      ]
    }
  }
}

重新启动Claude Desktop，然后尝试：

• “俄勒冈州波特兰的天气怎么样？”
• “迈阿密有天气警报吗？”
• “本周西雅图会下雨吗？”
• “给我看看西雅图的天气仪表盘。”

Claude将调用您的MCP服务器的工具来获取实时数据！

第3部分：MCP应用程序仪表板

此存储库现在包括本教程第3部分的最小MCP应用程序实现：

• 工具： get_forecast_dashboard(latitude, longitude)
• UI资源： ui://weather/dashboard
• 运行时UI文件： src/weather_forecast_mcp_server/ui/weather_dashboard.html
• 反应源代码： mcp-app-ui/src/main.jsx

它是如何工作的：

1. 该工具从NWS获取预测数据，并在中返回图表就绪数据 _meta.forecast.
2. 工具元数据声明 _meta.ui.resourceUri = "ui://weather/dashboard".
3. 支持Apps的MCP主机渲染仪表板资源并将工具结果传递给iframe。

构建React用户界面

仪表板采用混合方法：

• Python/FastMCP提供工具/资源和协议行为。
• React（Vite）处理UI渲染和交互。

从存储库根目录：

cd mcp-app-ui
npm install
npm run build

这将单个文件仪表板工件写入：

• src/weather_forecast_mcp_server/ui/weather_dashboard.html

Claude桌面渲染（推荐桥接服务器）

如果您的客户端发现了该工具，但没有呈现应用程序面板，请运行ext-apps桥服务器以获得最大的主机兼容性。

安装并从存储库根目录启动：

cd mcp-app-server
npm install
node server.mjs

Claude桌面配置条目：

{
  "mcpServers": {
    "weather-app-bridge": {
      "command": "node",
      "args": [
        "/absolute/path/to/weather-forecast-mcp-server/mcp-app-server/server.mjs"
      ]
    }
  }
}

然后开始新的聊天并拨打电话：

• weather-app-bridge:get_forecast_dashboard

如果Claude仍然以纯文本或自行生成的仪表板进行响应：

• 确保您的应用程序HTML已重建(mcp-app-ui/npm run build)更改后。
• 确认渲染的应用程序页脚包含 Powered by weather-forecast-mcp-server （视觉指纹）。
• 继续使用上面的网桥服务器路径；它遵循官方 ext-apps 服务器注册模式。
• 重新启动后打开一个新的聊天（工具/资源发现可以缓存会话）。

快速验证

1. 使用stdio传输启动服务器(uv run mcp run src/weather_forecast_mcp_server/server.py).
2. 连接支持应用程序的MCP主机。
3. 调用 get_forecast_dashboard 美国坐标。
4. 确认交互式仪表板渲染并在温度、降水和风视图之间切换。

当前限制

• UI到模型的上下文更新依赖于主机，并非在所有客户端都能保证。
• 应用程序渲染依赖于主机；一些MCP工具可以在不渲染iframe UI的情况下显示工具输出。
• 预报覆盖率仍然是美国唯一的，因为它取决于美国国家气象局API。

Docker部署

对于生产部署，使用Docker进行进程隔离和安全：

构建并运行

塑造形象

docker compose build

运行容器

docker compose up -d

查看日志

docker compose logs -f weather-mcp

安全特性

Docker设置包括：

• ✅ 非root用户(mcpuser)
• ✅ 只读文件系统
• ✅ 无特权升级
• ✅ 资源限制（CPU/内存）
• ✅ 健康检查

HTTP传输（可选）

对于远程访问，请修改 server.py 要使用HTTP传输：

if __name__ == "__main__":
    import sys
    if "--http" in sys.argv:
        mcp.run(transport="http", host="0.0.0.0", port=8000)
    else:
        mcp.run()  # Default stdio

更新Dockerfile CMD并在中公开端口8000 compose.yml.

运作原理

此服务器实现 MCP规范2025-11-25:

weather-forecast-mcp-server/
├── src/weather_forecast_mcp_server/
│   ├── server.py                  # FastMCP server with tools/resources
│   └── ui/weather_dashboard.html  # MCP App dashboard resource
├── pyproject.toml          # Dependencies and metadata
├── Dockerfile              # Production container
└── compose.yml             # Docker orchestration

建筑

1. MCP主机 （Claude Desktop、VS Code等）生成服务器进程
2. JSON-RPC 2.0 通过stdio或HTTP交换的消息
3. FastMCP 处理协议细节（能力协商、工具注册）
4. 异步I/O 具有用于非阻塞API请求的httpx
5. 结构化响应 以JSON格式返回给主机

可用工具

geocode_city(city_name: str)

• 将城市名称转换为坐标
• 使用Nomatim OpenStreetMap API
• 返回lat、lon和显示名称

get_forecast(latitude: float, longitude: float)

• 获取完整的天气预报
• 返回当前状况、7天预测、每小时数据和警报
• 美国国家气象局API（仅限美国）

get_alerts(latitude: float, longitude: float)

• 获取活动天气警报
• 返回警告、观察和建议
• 包括严重性、紧迫性和到期时间

get_forecast_dashboard(latitude: float, longitude: float)

• 在UI友好的有效负载中返回7天/昼夜时段
• 包含 _meta.forecast 和 _meta.location 用于仪表板渲染
• 宣布 ui://weather/dashboard 适用于MCP应用程序主机

可用资源

weather://climate/normals/{location}/{month}

• 读取30年气候正常值（1991-2020）
• 示例URI： weather://climate/normals/seattle-wa/01
• 需要 NOAA_API_TOKEN 用于NOAA CDO API访问

ui://weather/dashboard

• 提供可嵌入的HTML仪表板资源
• MIME类型： text/html;profile=mcp-app
• 被...使用 get_forecast_dashboard

与代理技能相比

此服务器提供 相同的天气功能 随着 代理技能版本，但具有不同的架构：

何时使用此MCP服务器：

• 具有SLA的生产部署
• 多个客户端访问该服务
• 需要安全隔离
• 企业/组织政策
• 需要远程访问（HTTP传输）

何时使用代理技能：

• 快速原型制作
• 个人生产力
• 受信任的本地代码
• 基于文件系统的发现就足够了

支持的平台

• ✅ 克劳德桌面版 （stdio）
• ✅ API克劳德 （HTTP）
• ✅ VS代码与副本 （stdio）
• ✅ 光标 （stdio）
• ✅ 自定义MCP客户端（stdio或HTTP）

API覆盖范围

使用 美国国家气象局API:

• 🇺🇸 美国所有州和地区
• 🇵🇷 波多黎各、美属维尔京群岛
• 🇬🇺 关岛、美属萨摩亚

备注：对于国际天气，请使用OpenWeatherMap或WeatherAPI进行扩展。

了解更多

📖 阅读完整教程: 构建您的第一台MCP服务器

此存储库附带了一个全面的教程，涵盖：

• 使用FastMCP实现MCP服务器
• stdio与HTTP传输
• Docker容器化用于生产
• 安全最佳实践
• 与Agent技能架构的比较

需求

• Python 3.10+
• 紫外线 （推荐）或pip
• 依赖关系：请参见 pyproject.toml
• Docker（可选，用于容器化部署）

验证

运行与释放门控相同的检查：

uv run python -m py_compile src/weather_forecast_mcp_server/server.py
timeout 8s uv run mcp run src/weather_forecast_mcp_server/server.py
uv run python - <<'PY'
import asyncio
from weather_forecast_mcp_server.server import geocode_city
print(asyncio.run(geocode_city("Seattle, WA")))
PY
docker compose -f compose.yml config
docker compose -f compose.yml build weather-mcp
uv run --group dev pytest

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

贡献的想法

• \[\]添加提示功能（常见天气查询）
• \[\]实现缓存层（Redis）
• \[\]添加HTTP传输的身份验证
• \[\]支持国际天气API
• \[\]添加度量和可观察性（Prometheus）

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

归因

由...创建 尼尔斯·弗里德里希斯 作为MCP生态系统的一部分。

天气数据来自：

• 美国国家气象局API
• 提名（OpenStreetMap）

相关项目

• MCP规范
• MCP Python SDK
• 代理技能版本 -基于文件系统的替代方案
• LightNow MCP注册表 -发现更多MCP服务器

______________________________________________________________________