🌩️ MCP Weather Alerts Tool using FastMCP + Claude Desktop

This project demonstrates how to build an MCP (Model Context Protocol) tool using the official FastMCP Python SDK. It integrates with Claude Desktop to enable an AI assistant to retrieve weather alerts by U.S. state via the api.weather.gov API.

🚀 What This Project Does

• ✅ Implements a custom MCP server with FastMCP
• 🌐 Uses httpx to call real-time weather alerts from api.weather.gov
• 📦 Returns structured information: event, severity, description, and instructions
• 🧠 Integrates with Claude Desktop
• 🌈 Can be tested interactively via MCP Inspector

🧱 Tech Stack

📁 Project Structure

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!

🧠 Tool Logic: 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")
    ]

🛠️ Installation & Setup

1. Create & Configure Project

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. Add Your Tool

Place your weather.py in the server/ folder, containing the logic for get_alerts.

🧪 Run & Inspect

Launch with MCP Inspector

uv run mcp dev server/weather.py

Then open http://localhost:6757 to:

• View your get_alerts tool
• Try calling it with input like "TX"

🤖 Claude Desktop Integration

1. Update your claude_desktop_config.json:

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

2. Restart Claude Desktop
3. Prompt:

   "What are the weather alerts for Texas?"

Claude will call your MCP tool and display structured output.

💡 What is MCP?

The Model Context Protocol standardizes how apps send context (data, tools, prompts) to LLMs. It separates the "context provider" from the LLM layer.

Three core primitives:

📎 Credits

• FastMCP Python SDK
• api.weather.gov
• Claude Desktop
• Project structure based on examples from the official MCP docs

📄 License

This project is open-sourced under the MIT License.