Ambient Weather MCP Server

An MCP (Model Context Protocol) server that connects AI assistants to Ambient Weather personal weather station data. Ask natural language questions about your weather station instead of parsing raw JSON from the API.

What It Does

This server exposes your Ambient Weather station data as MCP tools. Connect it to Claude Desktop, VS Code, or Kiro, and you can ask things like:

"List my weather stations"
"What's the current temperature at my station?"
"What are the conditions at CC:7B:5C:51:EC:52?"

The AI calls the tool, the server fetches live data from the Ambient Weather REST API, and the AI presents the result in natural language.

Architecture

┌──────────────────┐    stdio (JSON-RPC)    ┌────────────────────┐
│   MCP Client     │◄─────────────────────►│   MCP Server       │
│  Claude Desktop  │                        │   (this project)   │
│  VS Code / Kiro  │                        │                    │
└──────────────────┘                        │  src/server.py     │
                                            │    ↓ calls          │
                                            │  src/ambient_client │
                                            │    ↓ HTTPS          │
                                            └────────┬───────────┘
                                                     │
                                            ┌────────▼───────────┐
                                            │  Ambient Weather   │
                                            │  REST API          │
                                            │  rt.ambientweather │
                                            │  .net/v1           │
                                            └────────────────────┘

Available Tools

| Tool | Description | Parameters | |------|-------------|------------| | ping | Health check — confirms server is running and keys are configured | None | | get_devices | Lists all weather stations on the account with latest readings | None | | get_current_weather | Full weather report from a specific station | mac_address |

Prerequisites

Ambient Weather API keys — generate both at https://dashboard.ambientweather.net/account

Application Key: identifies the MCP server app
API Key: grants read access to device data

Python 3.13+ installed
uv — modern Python package manager. Install: curl -LsSf https://astral.sh/uv/install.sh | sh
An Ambient Weather station reporting to ambientweather.net (or access to someone's API key who has one)

Setup (Local Development)

# Clone the repo
git clone https://github.com/NanaGyamfiPrempeh30/ambient-weather-mcp.git
cd ambient-weather-mcp

# Install dependencies (uv creates .venv automatically)
uv sync

# Configure API keys
cp .env.example .env
# Edit .env with your actual keys

# Test the server
uv run python -c "from src.server import ping; import asyncio; print(asyncio.run(ping()))"

You should see: `` Ambient Weather MCP server is running. API Key: configured Application Key: configured API Client: ready ``

Connecting to Claude Desktop

Windows (with batch file)

Create run_mcp.bat in the project root:

@echo off
cd /d C:\Users\YourUsername\ambient-weather-mcp
C:\Python313\python.exe -m src

Add to claude_desktop_config.json (found at %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "ambient-weather": {
      "command": "cmd.exe",
      "args": ["/c", "C:\\Users\\YourUsername\\ambient-weather-mcp\\run_mcp.bat"],
      "env": {
        "AMBIENT_API_KEY": "your-api-key",
        "AMBIENT_APP_KEY": "your-application-key"
      }
    }
  }
}

macOS / Linux (direct)

Add to Claude Desktop config: ``json { "mcpServers": { "ambient-weather": { "command": "uv", "args": ["run", "python", "-m", "src"], "cwd": "/path/to/ambient-weather-mcp", "env": { "AMBIENT_API_KEY": "your-api-key", "AMBIENT_APP_KEY": "your-application-key" } } } } ``

Restart Claude Desktop fully (quit from system tray, reopen).
Check Settings → Developer → ambient-weather shows running.
In a new chat, ask: "Use the get_devices tool to list my weather stations"

Running with Docker

# Build
docker build -t ambient-weather-mcp .

# Run
docker run -i --rm \
  -e AMBIENT_API_KEY="your-api-key" \
  -e AMBIENT_APP_KEY="your-app-key" \
  ambient-weather-mcp

The Docker image is also published to GitHub Container Registry on every push to main: ``bash docker pull ghcr.io/nanagyamfiprempeh30/ambient-weather-mcp:latest ``

CI/CD

Every push to main triggers two GitHub Actions workflows:

Build and Push — builds the Docker image, runs a smoke test, and pushes to ghcr.io with latest and commit SHA tags
Secret Scanning — runs TruffleHog to detect accidentally committed secrets

A pre-commit hook (TruffleHog) also scans locally before every commit. See .pre-commit-config.yaml for setup instructions.

Project Structure

ambient-weather-mcp/
├── .github/
│   └── workflows/
│       ├── build-and-push.yml   # Docker build + push to ghcr.io
│       └── secret-scan.yml      # TruffleHog secret scanning
├── .kiro/
│   └── specs/
│       ├── requirements.md      # EARS-format requirements
│       ├── design.md            # Technical architecture
│       └── tasks.md             # Implementation tasks
├── kubernetes/
│   ├── namespace.yaml
│   ├── deployment.yaml
│   ├── service.yaml
│   ├── ingress.yaml
│   ├── servicemonitor.yaml
│   └── secret.yaml.example     # Secret template (safe to commit)
├── src/
│   ├── __init__.py              # Package marker
│   ├── __main__.py              # Entry point for python -m src
│   ├── server.py                # MCP server + tool definitions
│   └── ambient_client.py        # Ambient Weather REST API client
├── .env.example                 # API key template (safe to commit)
├── .gitignore                   # Excludes .env, .venv, __pycache__
├── .dockerignore                # Excludes secrets from Docker image
├── .pre-commit-config.yaml      # TruffleHog pre-commit hook
├── Dockerfile                   # Container build recipe (uses uv)
├── pyproject.toml               # Python dependencies (managed by uv)
├── uv.lock                      # Locked dependency versions
├── run_mcp.bat                  # Windows launcher for Claude Desktop
├── DEBUG_LOG.md                 # Error tracking log
└── README.md                    # This file

API Rate Limits

The Ambient Weather API enforces:

1 request/second per API key
3 requests/second per Application key

The server includes a 60-second TTL cache to stay within these limits automatically. Weather stations only report every 5 minutes, so caching loses nothing.

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | AMBIENT_API_KEY | Yes | Ambient Weather API key | | AMBIENT_APP_KEY | Yes | Ambient Weather Application key | | CACHE_TTL_SECONDS | No | Cache duration in seconds (default: 60) | | LOG_LEVEL | No | DEBUG, INFO, WARNING, ERROR (default: INFO) |

Troubleshooting

"No module named src" — Make sure you're running from the project root directory. On Windows with Claude Desktop, use the cmd.exe + batch file method shown above.

"Server disconnected" in Claude Desktop — On Windows, use the cmd.exe + batch file method. Direct Python execution has working directory issues with Claude Desktop on Windows.

"401 Unauthorized" — API keys are invalid. Regenerate at https://dashboard.ambientweather.net/account

"No weather stations found" — The API key doesn't have any stations attached. You need a physical Ambient Weather station registered to the account.

"429 Too Many Requests" — Rate limit hit. Wait a few seconds. Increase CACHE_TTL_SECONDS if it keeps happening.

See DEBUG_LOG.md for a full history of issues encountered and their resolutions.

What's Next

[x] CI/CD pipeline (GitHub Actions → ghcr.io)
[x] Kubernetes manifests for ArgoCD deployment
[x] Kiro spec-driven workflow (requirements, design, tasks)
[x] TruffleHog secret scanning (pre-commit + GitHub Actions)
[x] Migrate from pip to uv
[ ] get_weather_history tool for historical data queries
[ ] Security scanning tools (ruff, bandit, semgrep, safety)
[ ] Replace .env with proper secrets management
[ ] HTTP transport for network-based deployment
[ ] Publish to MCP marketplaces (mcp.so, Smithery, Sevalla)
[ ] MCP OAuth authorization for secure multi-user access
[ ] Medium article as Claude Partner Network case study

Credits

Ambient Weather API
Model Context Protocol
FastMCP
Built by Yaw Nana Gyamfi Prempeh
Wilson Mar — mentorship, weather station access, MCP reference, weather-info

License

MIT

ambient-weather-mcp