# ambient-mcp

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that wraps the [Ambient Weather REST API](https://ambientweather.docs.apiary.io/). Query your personal weather stations conversationally from Claude Code, Claude.ai, or any MCP-compatible client.

## Tools

| Tool | Description |
|------|-------------|
| `get_devices` | List all stations on the account with metadata and the latest observation (`lastData`) |
| `get_latest_observation` | Most recent reading for a single station — served from the devices cache, no extra API call |
| `get_historical_data` | Recent observations for a single station, paginated by `days` (default 1, max 30; newest-first) |
| `reset_cache` | Clear the in-process cache |

## Configuration

Get an Application Key and API Key from <https://ambientweather.net/account>. Both are required:

```
AMBIENT_APP_KEY=...
AMBIENT_API_KEY=...
```

The Ambient Weather API is rate-limited to **1 request per second per API key**, so this server keeps an in-process cache with a 10-minute TTL (stations typically report every 5 minutes).

## Run locally (stdio)

```bash
pip install -r requirements.txt
cp .env.example .env  # fill in keys
python server.py
```

### Connect to Claude Code

Add to `~/.claude.json` under `mcpServers`:

```json
{
  "mcpServers": {
    "ambient": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/ambient-mcp/server.py"],
      "env": {
        "AMBIENT_APP_KEY": "your_application_key_here",
        "AMBIENT_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Run hosted (HTTP)

Set `MCP_TRANSPORT=streamable-http` and the server exposes a Streamable HTTP endpoint on `PORT` (default `8000`). The included `Dockerfile` defaults to this mode.

```bash
docker build -t ambient-mcp .
docker run --rm -p 8000:8000 \
  -e AMBIENT_APP_KEY=... \
  -e AMBIENT_API_KEY=... \
  ambient-mcp
```

### Hosting options

| Option | Approx. cost | Notes |
|--------|-------------|-------|
| Azure Container Apps | ~$0/month | Scales to zero; free tier covers low-frequency weather queries |
| AWS App Runner | ~$5–11/month | Always-on, no cold starts |
| Railway | ~$0 free / ~$5/month | Simplest GitHub-connected deploy |

When hosted, add a `MCP_AUTH_TOKEN` environment variable on the platform and configure the client to send `Authorization: Bearer <token>`.

### Connect to Claude.ai or Claude Code (HTTP)

```json
{
  "mcpServers": {
    "ambient": {
      "type": "http",
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
    }
  }
}
```

## Project structure

```
ambient_client.py   # httpx-based REST client (list_devices, get_device_data)
server.py           # FastMCP tool definitions + in-process cache + transport toggle
requirements.txt
Dockerfile          # python:3.11-slim, streamable-http transport by default
.env.example
```