mcp-weather-alert-tool

# 🌩️ MCP Weather Alerts Tool using FastMCP + Claude Desktop This project demonstrates how to build an **MCP (Model Context Protocol)** tool using the official [`FastMCP`](https://github.com/modelcontextprotocol/python-sdk) 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](https://www.weather.gov/documentation/services-web-api) - 📦 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` ```python @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 ```bash 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 ```bash uv run mcp dev server/weather.py ``` Then open [http://localhost:6757](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`: ```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](https://modelcontextprotocol.io) 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](https://github.com/modelcontextprotocol/python-sdk) - [api.weather.gov](https://www.weather.gov/documentation/services-web-api) - [Claude Desktop](https://claude.ai/) - Project structure based on examples from the [official MCP docs](https://modelcontextprotocol.io) --- ## 📄 License This project is open-sourced under the MIT License.