🌩️ MCP Weather Alerts Tool using FastMCP + Claude Desktop

🌩️ 使用 FastMCP + Claude Desktop 构建 MCP 天气警报工具

本项目演示如何使用官方 FastMCP Python SDK 构建 MCP（Model Context Protocol） 工具。它与 Claude Desktop 集成，让 AI 助手能够通过 api.weather.gov API 按美国州查询天气警报。

---

🚀 本项目的功能

• ✅ 使用 FastMCP 实现自定义 MCP 服务
• 🌐 使用 httpx 从 api.weather.gov 获取实时天气警报
• 📦 返回结构化信息：事件、严重程度、描述和说明
• 🧠 与 Claude Desktop 集成
• 🌈 可通过 MCP Inspector 交互式测试

---

🧱 技术栈

工具/库	用途
mcp[cli]	提供命令行工具的 MCP 服务工具包
httpx	异步 HTTP 客户端
uv	现代 Python 包/依赖管理器
Claude Desktop	用于大模型 + MCP 的 AI 界面
MCP Inspector	用于调试 MCP 端点的 UI

---

📁 项目结构

mcpcrashcourse/
├── server/
│   └── weather.py         # MCP server logic (get_alerts)
├── pyproject.toml         # Project metadata + dependencies
├── uv.lock                # Locked versions (auto-generated by uv)
└── README.md              # You're reading it!

---

🧠 工具逻辑：get_alerts

@mcp.tool()
async def get_alerts(state: str) -> list[dict]:
    # Fetch weather alerts for a given U.S. state (e.g., 'CA')
    url = "https://api.weather.gov/alerts/active"
    params = {"area": state.upper()}
    async with httpx.AsyncClient() as client:
        response = await client.get(url, params=params)
        data = response.json()

    return [
        {
            "event": alert.get("event"),
            "severity": alert.get("severity"),
            "description": alert.get("description"),
            "instruction": alert.get("instruction"),
        }
        for alert in data.get("features", [])
        if alert.get("properties")
    ]

---

🛠️ 安装与设置

1. 创建并配置项目

pipx install uv               # install uv if you haven't
uv init mcpcrashcourse        # start new project
cd mcpcrashcourse
uv add "mcp[cli]" httpx       # add dependencies

2. 添加工具

将 weather.py 放入 server/ 文件夹，其中包含 get_alerts 的逻辑。

---

🧪 运行与检查

使用 MCP Inspector 启动

uv run mcp dev server/weather.py

然后打开 http://localhost:6757 来：

• 查看 get_alerts 工具
• 尝试使用类似 "TX" 的输入调用它

---

🤖 Claude Desktop 集成

1. 更新 claude_desktop_config.json：

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "<your-project-directory>/server/weather.py"
      ]
    }
  }
}

2. 重启 Claude Desktop
3. 提示词：

   “德克萨斯州有哪些天气警报？”

Claude 将调用你的 MCP 工具并显示结构化输出。

---

💡 什么是 MCP？

Model Context Protocol 规范了应用如何向大模型发送上下文（数据、工具、提示词）。它将**“上下文提供方”**与大模型层分离。

三种核心原语：

类型	使用场景	类比
工具	执行函数	POST 端点
资源	提供静态数据	GET 端点
提示词	可重复使用的交互	大模型模板

---

📎 致谢

• FastMCP Python SDK
• api.weather.gov
• Claude Desktop
• 项目结构参考了 MCP 官方文档中的示例

---

📄 许可证

本项目基于 MIT 许可证开源。