Ambient Weather

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

1. 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
2. Python 3.13+ installed
3. uv — modern Python package manager. Install: curl -LsSf https://astral.sh/uv/install.sh | sh
4. 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)

1. Create run_mcp.bat in the project root:

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

2. 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:

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

3. Restart Claude Desktop fully (quit from system tray, reopen).
4. Check Settings → Developer → ambient-weather shows running.
5. 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:

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

• CI/CD pipeline (GitHub Actions → ghcr.io)
• Kubernetes manifests for ArgoCD deployment
• Kiro spec-driven workflow (requirements, design, tasks)
• TruffleHog secret scanning (pre-commit + GitHub Actions)
• 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