edudele/cumulusmx-mcp repository overview

⁠cumulusmx-mcp

MCP server that exposes a CumulusMX⁠ weather station to any LLM via the Model Context Protocol⁠.

Built with FastMCP⁠ and deployed as a Docker container. Designed to sit behind a reverse proxy (e.g. Pangolin⁠) so your station is never exposed directly.

⁠Features

• Current conditions — temperature, humidity, pressure, wind, rain, solar/UV in real time.
• Today / yesterday — highs, lows and times for all variables.
• Historical data & Analytics — daily summaries from dayfile across all years, flexible column alias filtering (date, mintemp, rain, etc.) and aggregated statistical summaries (summary_only).
• Agronomy & climate tools — climatology (monthly normals), frost_dates (last spring / first autumn frost, frost-free period), degree_days (growing degree days), wind_rose (16-point rose) and daily_briefing (live conditions + yesterday in context + month vs normal + streaks in progress).
• Full CumulusMX API coverage — read and write: every settings section (get_settings / update_settings with merge, dry_run preview and no blind writes), dedicated MySQL and MQTT tools (get_/update_mysql_settings, mysql_table, get_/update_mqtt_settings, mysql_cache), history corrections (edit_dayfile, edit_datalog, edit_recent_data, edit_records), diary import/export, interval_data / daily_data, records_query, custom charts, WebSocket live_sample and HTTP station input. See API coverage⁠.
• Safety net for the write tools — every write is audited (log + optional JSON-Lines file, secrets masked), the previous state is backed up automatically and can be undone with restore_backup, and an optional read-only token lets others query the station without being able to change anything (it does not even see the write tools). See Security model⁠.
• Alerts and reports — weather_alerts (frost, wind, rain, heat, UV, pressure drop...) and period_report (a shareable Markdown weekly / monthly / yearly report compared with the station's own normals).
• Observable — GET /metrics exposes Prometheus metrics: tool calls and latency, writes by outcome, requests to CumulusMX, whether the station is reachable, stored backups. See Monitoring⁠.
• Runs anywhere — Docker, pip/uvx, or stdio for local clients such as Claude Desktop. Pinned dependencies, tested on FastMCP 3.x and 4.x and Python 3.10 - 3.13.
• Resilient — GET requests to CumulusMX are retried with backoff on transient failures; timeouts are configurable.
• Agent-ready — the server sends usage instructions to MCP clients (which tool for which question, units, decimal conventions, write-tool etiquette).
• Climate analytics — count_days, find_streaks, anomaly and data_quality answer "how many days above 35 °C?", "longest dry spell?", "was this July warmer than normal?" and "can I trust the history?" from the station's own data, with no extra CumulusMX endpoints.
• Historical rankings & Annual records — competition rankings (1, 2, 2, 4) for extremes (heat, cold, rain, wind gusts) and yearly records summaries.
• MCP Resources — declarative weather:// resources for direct context retrieval in MCP clients.
• MCP Prompts — ready-to-use guided prompts for daily analysis, extreme events, annual summaries, and period comparisons.
• Records — all-time, this year, this month, by calendar month or custom date range.
• Graphs — recent and daily graph data series with statistical downsampling (graph_summary).
• NOAA reports — monthly and annual plain-text reports.
• Webtags — query any CumulusMX webtag by name or evaluate webtag templates.
• Health check — unauthenticated /health endpoint for Docker and monitoring orchestrators.
• Bearer token auth — all MCP endpoints require Authorization: Bearer ***.
• Prefix stripping — configurable middleware for reverse proxies that don't rewrite paths.
• Agent skill — ready-to-use skills/cumulusmx-weather⁠ that teaches an agent when and how to use these tools (see Agent skill⁠).
• MCP Tool Annotations — full readOnlyHint and destructiveHint annotations for client permission grouping (read-only vs write/delete in Claude and other clients).

⁠Quick start

⁠Docker

The image is multi-architecture (linux/amd64 and linux/arm64), so it runs the same on a PC, a NAS or a Raspberry Pi.

docker run -d \
  -e MCP_AUTH_TOKEN=your-secret-token \
  -e CUMULUSMX_URL=http://your-cumulusmx-host:8998 \
  -p 8000:8000 \
  edudele/cumulusmx-mcp

⁠Python package (pip / uvx) and stdio

pip install cumulusmx-mcp      # or: uvx cumulusmx-mcp   (development version: pip install git+https://github.com/edudele/cumulusmx-mcp)
CUMULUSMX_URL=http://your-cumulusmx-host:8998 MCP_AUTH_TOKEN=secret cumulusmx-mcp           # HTTP on :8000
cumulusmx-mcp --transport stdio                                                          # local MCP client (no HTTP, no token)

Claude Desktop (or any stdio client):

{
  "mcpServers": {
    "cumulusmx": {
      "command": "cumulusmx-mcp",
      "args": ["--transport", "stdio"],
      "env": { "CUMULUSMX_URL": "http://192.168.1.10:8998" }
    }
  }
}

In stdio mode the process is started by your client and nobody else can reach it, so there is no Bearer token.

⁠Docker Compose

services:
  cumulusmx-mcp:
    image: edudele/cumulusmx-mcp
    environment:
      MCP_AUTH_TOKEN: your-secret-token
      CUMULUSMX_URL: http://cumulusmx:8998   # adjust to your CumulusMX host
      PORT: 8000
      MCP_STRIP_PREFIX: ""                   # set if behind a prefix-routing proxy
      CUMULUS_DATA_START_YEAR: 2023          # start year for historical rankings
      CUMULUS_FROST_THRESHOLD: 0.0           # threshold in °C for frost day counts
      CUMULUS_CACHE_TTL: 600                 # dayfile cache TTL in seconds
    ports:
      - "8000:8000"
    restart: unless-stopped

See .env.example⁠ for all variables.

⁠Environment variables

⁠Security model

Keep the server behind HTTPS (a reverse proxy) when it is reachable from outside your network.

⁠Health check

An unauthenticated health check endpoint is exposed at http://localhost:8000/health (or /health on your host/proxy). It returns:

{"status": "healthy", "service": "cumulusmx-mcp", "version": "1.8.1"}

The Docker container includes a native HEALTHCHECK directive verifying this endpoint with Python's standard urllib.request.

⁠Reverse proxy

The server is designed to work with proxies that use path-prefix routing (e.g. Pangolin with clip prefix / rewrite mode). Set MCP_STRIP_PREFIX to the prefix your proxy uses so the server sees clean paths.

Example with Pangolin routing https://your-domain.com/mcp-res → http://cumulusmx-mcp:8000:

MCP_STRIP_PREFIX=/mcp-res

⁠MCP endpoint

https://your-domain.com/mcp-res/mcp

Add it to your MCP client (e.g. Hermes, Claude Desktop) with:

{
  "mcpServers": {
    "cumulusmx": {
      "url": "https://your-domain.com/mcp-res/mcp",
      "headers": {
        "Authorization": "Bearer your-secret-token"
      }
    }
  }
}

⁠Available tools

⁠System & Maintenance (/utils/*)

⁠Reports & Upload (/genreports/, /uploadreport/)

⁠Diagnostics (/data/errorlog.json)

⁠Alerts, reports and safety net

⁠Configuration, MySQL & MQTT

⁠Data access, queries and real time

⁠History corrections, diary and device input (write)

⁠Data Editing (/edit/*)

⁠Configuration (/settings/, /setsettings/)

⁠API coverage

Checked against the Api.cs controllers of CumulusMX 5.2.0 (217 named endpoints):

The write operations were verified against the CumulusMX source and with mocked tests; they are not exercised against a live station by the test suite. Settings and editors take effect on the real station, so use dry_run for settings and keep backups before editing history.

⁠MCP Resources

FastMCP declarative resources available for direct context reading:

⁠MCP Prompts

Ready-to-use guided prompts for AI assistants:

⁠Agent skill

The repository ships an agent skill in skills/cumulusmx-weather/⁠. The MCP server provides the tools; the skill tells the agent when to use each one (for example `r