🌩️ 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

Tool/Library	Purpose
mcp[cli]	MCP server toolkit with CLI tools
httpx	Async HTTP client
uv	Modern Python package/dependency manager
Claude Desktop	AI interface for LLM + MCP
MCP Inspector	UI to debug MCP endpoints

---

📁 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:

Type	Use Case	Analogy
Tools	Execute functions	POST endpoint
Resources	Provide static data	GET endpoint
Prompts	Reusable interactions	LLM templates

---

📎 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.