weather-mcp-demo

# Weather MCP Demo：基于 FastMCP 的天气查询工具

项目简介

本项目使用 Python + FastMCP + Open-Meteo API 实现一个本地 MCP Server，让大模型客户端可以调用天气查询工具。

项目通过 Open-Meteo 的 Geocoding API 查询城市经纬度，再通过 Forecast API 查询实时天气。整个过程不需要 API Key，适合本地开发、课程展示和实习面试讲解。

Related MCP server: Simple Weather MCP

项目功能

• 根据城市名查询实时天气

• 根据经纬度查询实时天气

• 支持中文城市名和英文城市名

• 返回温度、体感温度、湿度、天气状态、风速、风向

• 支持本地 MCP Client 测试，无 Claude 额度也能验证

技术栈

• Python

• FastMCP

• MCP Python SDK

• Open-Meteo API

• requests

• stdio

项目结构

weather-mcp-demo/
├── server.py
├── test_weather.py
├── test_mcp_client.py
├── requirements.txt
└── README.md

核心文件说明：

• server.py：MCP Server 主程序，使用 FastMCP 暴露天气查询工具

• test_weather.py：普通 Python 测试脚本，用来验证 Open-Meteo API 逻辑

• test_mcp_client.py：本地 MCP Client 测试脚本，用来模拟客户端调用 MCP 工具

• requirements.txt：项目依赖

• README.md：项目说明文档

运行步骤

进入项目目录：

cd weather-mcp-demo

安装依赖：

python -m pip install -r requirements.txt

先测试普通 API 逻辑：

python test_weather.py

再测试 MCP Client 调用工具：

python test_mcp_client.py

最后可以直接启动 MCP Server：

python server.py

重点解释

test_weather.py 的作用

test_weather.py 用来测试普通 API 逻辑。

它不会启动 MCP Server，而是直接导入 server.py 中的天气查询函数，验证：

• 城市名能否正确转换为经纬度

• Open-Meteo Forecast API 是否能返回实时天气

• 天气结果是否能格式化成中文报告

这个脚本适合在开发阶段先确认核心业务逻辑是否正常。

test_mcp_client.py 的作用

test_mcp_client.py 用来模拟 MCP 客户端调用工具。

它的意义是：即使没有 Claude 额度，也可以在本地验证 MCP Server 是否真的暴露了工具、工具是否能被客户端调用、返回结果是否正确。

这比只运行 server.py 更适合调试和面试演示。

server.py 的 stdio 模式

server.py 使用 stdio 模式运行。

stdio 模式下，MCP Server 通过标准输入和标准输出与 MCP Client 通信。因此单独运行：

python server.py

终端没有普通输出是正常的。它不是卡死，而是在等待 MCP Client 发送协议消息。

面试讲解版流程

用户输入城市名 -> Geocoding API 获取经纬度 -> Forecast API 获取实时天气 -> MCP tool 封装结果 -> MCP Client/Claude 调用工具。

可以这样讲：

1. 用户输入城市名，例如“杭州”或 Tokyo。

2. MCP Client 或 Claude 调用 get_weather 工具。

3. server.py 先把中文城市名映射成英文城市名，例如“杭州”映射为 Hangzhou。

4. 程序调用 Open-Meteo Geocoding API，把城市名转换成经纬度。

5. 程序调用 Open-Meteo Forecast API，根据经纬度查询实时天气。

6. 程序把温度、体感温度、湿度、天气状态、风速、风向整理成中文报告。

7. MCP tool 把结果返回给 MCP Client 或 Claude。

这个项目展示了一个完整的 MCP 工具调用链路：用户需求、工具调用、外部 API 查询、结果封装、返回给大模型客户端。

MCP 工具说明

get_weather

根据城市名查询实时天气。

参数：

• city：城市名，例如 杭州、上海、Tokyo

• country_code：可选国家代码，例如 CN、JP

get_weather_by_location

根据经纬度查询实时天气。

参数：

• latitude：纬度

• longitude：经度

Claude Desktop 配置示例

如果要接入 Claude Desktop，可以在 Claude Desktop 的 MCP 配置中加入：

{
  "mcpServers": {
    "weather-mcp-demo": {
      "command": "你的conda环境python.exe绝对路径",
      "args": [
        "你的项目server.py绝对路径"
      ]
    }
  }
}

Windows 示例：

{
  "mcpServers": {
    "weather-mcp-demo": {
      "command": "C:\\Users\\你的用户名\\miniconda3\\envs\\weather-mcp-demo\\python.exe",
      "args": [
        "D:\\Proj\\mcp_weather\\weather-mcp-demo\\server.py"
      ]
    }
  }
}

注意：JSON 中的 Windows 路径反斜杠需要写成 \\。

常见问题

1. 为什么不用 API Key

因为项目使用的是 Open-Meteo API。

Open-Meteo 提供免费的 Geocoding API 和 Forecast API，基础天气查询不需要注册账号，也不需要 API Key。这样项目更容易本地运行，也更适合面试展示。

2. 为什么没有 Claude 额度也能测试

因为 MCP Server 本质上是一个本地工具服务。

除了 Claude Desktop，项目也可以使用本地 MCP Client 脚本调用工具。test_mcp_client.py 就是用来模拟 MCP Client 的，所以即使没有 Claude 额度，也可以验证 MCP 工具是否能正常工作。

3. 为什么 python server.py 看起来卡住

这是正常现象。

server.py 使用 stdio 模式运行，它启动后会等待 MCP Client 通过标准输入发送 MCP 协议消息。单独在终端运行时没有普通输出，看起来像卡住，其实是在等待客户端连接。

4. KeyboardInterrupt 是否是报错

如果你在终端运行 python server.py 后按下 Ctrl + C，可能会看到 KeyboardInterrupt。

这不是项目逻辑错误，而是你手动中断了正在等待客户端消息的 MCP Server。调试时可以直接关闭终端，或者按 Ctrl + C 停止服务。

面试时可以强调的点

• 项目没有使用需要 API Key 的服务，降低了运行门槛

• 支持中文和英文城市名，考虑了中文用户输入场景

• 拆分了普通 API 测试和 MCP Client 测试，方便定位问题

• 使用 FastMCP 暴露工具，代码结构简单，适合讲清楚 MCP 的工作方式

• server.py 不使用普通 print 输出，避免干扰 stdio 协议通信