ambient-mcp

License: MIT

An MCP (Model Context Protocol) server that wraps the Ambient Weather REST API. 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)

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:

{
  "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.

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)

{
  "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