MCP Server Weather

MCP 天气服务

一个使用 FastMCP 构建的简单天气微服务，通过 Open-Meteo API 提供天气预报和当前天气数据。

---

目录

• 功能
• 要求
• 安装
• 用法
• API 和工具架构
• 项目结构
• 架构
• 教程
• 贡献
• 许可证
• 作者

---

功能

• 获取天气预报，适用于任意位置（纬度/经度）
• 获取当前天气，适用于任意位置（纬度/经度）
• 异步 HTTP 请求，响应快速
• 可轻松集成为 MCP 工具

要求

• Python >= 3.13
• httpx >= 0.28.1
• mcp[cli] >= 1.9.2

安装

1. 克隆仓库：

   git clone https://github.com/yourusername/mcp-server-weather.git
   cd mcp-server-weather
   

2. （可选）创建并激活虚拟环境：

   python3 -m venv .venv
   source .venv/bin/activate
   

3. 安装依赖：

   pip install -r requirements.txt
   # or, if using pyproject.toml
   pip install .
   

用法

运行服务：

python server.py

该服务提供两个主要工具：

1. 获取天气预报

获取指定纬度和经度的每日天气预报。

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str

• **返回值：**格式化字符串，包含每日最高/最低气温、降水量和天气代码。

输出示例：

Date: 2024-06-01
Max Temperature: 22°C
Min Temperature: 14°C
Precipitation: 0.5 mm
Weather Code: 2
---
Date: 2024-06-02
Max Temperature: 20°C
Min Temperature: 13°C
Precipitation: 1.2 mm
Weather Code: 3

2. 获取当前天气

获取指定纬度和经度的当前天气数据。

@mcp.tool()
async def get_current_weather(latitude: float, longitude: float) -> str

• **返回值：**包含当前天气详情（气温、风、湿度等）的 JSON 字符串。

输出示例：

{
  "current": {
    "temperature_2m": 21.3,
    "is_day": 1,
    "showers": 0.0,
    "cloud_cover": 45,
    "wind_speed_10m": 5.2,
    "wind_direction_10m": 180,
    "pressure_msl": 1012.3,
    "snowfall": 0.0,
    "precipitation": 0.0,
    "relative_humidity_2m": 60,
    "apparent_temperature": 21.0,
    "rain": 0.0,
    "weather_code": 2,
    "surface_pressure": 1012.3,
    "wind_gusts_10m": 8.0
  }
}

API 和工具架构

• Open-Meteo API 文档

get_forecast

• 输入：
  • latitude（float）
  • longitude（float）
• 输出：
  • 包含每日天气数据的格式化字符串（参见上方示例）

get_current_weather

• 输入：
  • latitude（float）
  • longitude（float）
• 输出：
  • 包含当前天气数据的 JSON 对象（参见上方示例）

项目结构

.
├── server.py           # Main server code, defines weather tools
├── pyproject.toml      # Project metadata and dependencies
├── README.md           # Project documentation
├── project.md          # Project code summary
├── .gitignore          # Git ignore file
├── .python-version     # Python version file
├── uv.lock             # Lock file for uv package manager
├── .venv/              # Virtual environment (not committed)
└── __pycache__/        # Python cache files

架构

graph TD;
    A[Client (Claude Desktop, etc)] -- stdio --> B(MCP Server: server.py)
    B -- HTTPX async requests --> C(Open-Meteo API)
    B -- Exposes tools --> D[LLM/Client]
    B -- Returns weather data --> A

• 客户端：通过 stdio 连接到 MCP 服务（例如 Claude Desktop）
• MCP 服务：处理请求、提供工具并从 Open-Meteo 获取数据
• Open-Meteo API：提供天气和预报数据
• 大模型/客户端：使用数据并生成回复

---

教程

使用 Python 和 Open-Meteo API 创建 MCP 服务

MCP 服务通过将语言模型连接到数据源和服务来扩展其能力。

MCP 服务提供三种主要原语：

资源（由客户端控制）

• 按请求向客户端提供可用作上下文的数据。
• 如果你想被动地向 MCP 客户端提供数据或内容，并让客户端自行选择何时访问，请使用资源。

工具（由模型控制）

• 向客户端模型提供可执行的功能。
• 如果你想让客户端执行操作，例如从 API 请求内容、转换数据或发送电子邮件，请使用工具。

提示词（由用户控制）

• 向用户提供可重复使用的提示词和工作流。
• 如果你想让客户端向用户展示提示词和工作流，例如简化用户与资源或工具的交互，请使用提示词。

示例：将天气数据转换为自然语言

大模型非常擅长将数据转换为自然语言。例如，它们可以将气温、风速、露点等天气数据转换为对天气体感的描述，并给出穿衣建议。

分步教程

0. 要求

• Claude.ai 账户（所有账户类型均支持 MCP）
• Claude 桌面应用（macOS/Windows）
• 代码编辑器（例如 VS Code）
• uv（基于 Rust 的 Python 包管理器）
  • macOS：brew install uv
  • Windows：winget install --id=astral-sh.uv -e

1. 设置项目

要设置项目，请在代码编辑器中打开要添加项目的文件夹。然后按照以下步骤设置项目：

使用编辑器工具或终端创建一个名为 mcp-server-weather 的新文件夹：

mkdir mcp-server-weather

在终端中进入该文件夹：

cd mcp-server-weather

初始化一个新的 uv 项目：

uv init

使用 uv 创建虚拟环境：

uv venv

启动虚拟环境：

source .venv/bin/activate

注意：要停止虚拟环境，请在终端中运行 deactivate。

在虚拟环境中，使用 CLI 扩展安装 Python MCP SDK 和其他 Python 依赖项：

uv add "mcp[cli]" httpx

2. 构建天气 MCP 服务

创建 server.py 并添加以下框架代码：

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("weather")

# ... your code here ...

if __name__ == "__main__":
    mcp.run(transport='stdio')

添加常量和辅助函数

OPENMETEO_API_BASE = "https://api.open-meteo.com/v1"
USER_AGENT = "weather-app/1.0"

# Helper function to make a request to the Open-Meteo API
async def make_openmeteo_request(url: str) -> dict[str, Any] | None:
    """Make a request to the Open-Meteo API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

添加工具

@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    # ...

@mcp.tool()
async def get_current_weather(latitude: float, longitude: float) -> str:
    """Get current weather for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    
    url = f"{OPENMETEO_API_BASE}/forecast?latitude={latitude}&longitude={longitude}&current=temperature_2m,is_day,showers,cloud_cover,wind_speed_10m,wind_direction_10m,pressure_msl,snowfall,precipitation,relative_humidity_2m,apparent_temperature,rain,weather_code,surface_pressure,wind_gusts_10m"
    
    data = await make_openmeteo_request(url)

    if not data:
        return "Unable to fetch current weather data for this location."

    return data

3. 测试并运行 MCP 服务

mcp dev server.py

• 在浏览器中打开 http://localhost:5173
• 连接、列出工具，并使用纬度/经度进行测试

4. 扩展 MCP 服务

• 添加更多工具（例如 get_location）
• 使用 Open-Meteo Geocoding API 搜索位置

---

贡献

欢迎贡献！请提交 issue 或 pull request，帮助改进、修复错误或添加新功能。

许可证

MIT

作者

• ONE-FRONT tech，由 Michael Wybraniec 提供
• MCP Hands-On，由 Morten Rand-Hendriksen 提供