# Weather MCP Server

A demo [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI assistants (Claude, Copilot, Cursor, etc.) access to live US weather data via the free [National Weather Service API](https://www.weather.gov/documentation/services-web-api).

## Tools exposed

| Tool | Description |
|---|---|
| `get_forecast` | 3-period forecast for any US lat/long |
| `get_alerts` | Active weather alerts for a US state |
| `get_hourly` | Hourly forecast for next 12 hours |

No API key required — NWS is completely free.

---

## Local development

### 1. Install uv

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

### 2. Install dependencies

```bash
uv pip install "mcp[cli]>=1.0.0" "httpx>=0.27.0"
```

### 3. Run with MCP Inspector (for testing)

```bash
uv run mcp dev weather_server.py
```

Opens a browser UI to call your tools manually.

### 4. Connect to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "weather": {
      "command": "python",
      "args": ["/absolute/path/to/weather_server.py"]
    }
  }
}
```

Restart Claude Desktop. You'll see a 🔨 tools icon in chat.

---

## Deploy to Fly.io

### 1. Install flyctl

```bash
curl -L https://fly.io/install.sh | sh
```

### 2. Sign up / log in

```bash
fly auth signup   # or: fly auth login
```

### 3. Pick a unique app name

Edit `fly.toml` and change `app = "weather-mcp-demo"` to something unique.

### 4. Launch

```bash
fly launch --no-deploy   # reads fly.toml, provisions the app
fly deploy               # builds Docker image and deploys
```

Your server will be live at:
```
https://<your-app-name>.fly.dev/mcp
```

### 5. Connect Claude Desktop to the hosted server

```json
{
  "mcpServers": {
    "weather": {
      "url": "https://<your-app-name>.fly.dev/mcp"
    }
  }
}
```

### Useful Fly commands

```bash
fly logs          # tail live logs
fly status        # check machine health
fly deploy        # redeploy after code changes
fly scale count 1 # ensure at least 1 machine running
```

---

## Example prompts to try

- *"What's the weather forecast for New York City?"* → lat: 40.71, lon: -74.00
- *"Any weather alerts in Texas right now?"*
- *"Give me the hourly forecast for Miami."* → lat: 25.77, lon: -80.19