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 tip: write tools are enabled by default. If you only need to query your station, set ENABLE_WRITE_TOOLS=false: the 29 write tools are then not published at all (clients only see the 60 read-only tools), and they would refuse to run even if called directly.

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)

Back up before editing history. The edit_* tools rewrite dayfile.txt, log files and record files.

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 rankings for "hottest day ever", graph_summary instead of dumping thousands of points) and how to treat the write tools (always ask before changing the station).

To use it with Claude Code, copy the folder into your skills directory:

cp -r skills/cumulusmx-weather ~/.claude/skills/

Other agents that support SKILL.md folders can load it from the same directory. The skill requires this MCP server to be connected.

Development

git clone https://github.com/edudele/cumulusmx-mcp.git && cd cumulusmx-mcp
pip install -e ".[dev]"
python -m pytest -q            # ~370 tests, a few seconds; no CumulusMX needed (a simulator is included)
ruff check .

The code lives in the cumulusmx_mcp/ package, split by responsibility (config, HTTP client, day-file analytics, settings engine, one module of tools per domain...). server.py is only a compatibility shim. docs/ARCHITECTURE.md explains the layers, the rules the tests enforce and how to add a tool; CONTRIBUTING.md has the checklist. To smoke-test a deployed server (read-only calls only):

python scripts/smoke_readonly.py https://your-domain/mcp-res/mcp YOUR_TOKEN

Monitoring

GET /health (no token) is the liveness check. GET /metrics returns Prometheus metrics and needs the same Bearer token (the read-only token is enough). Example scrape configuration:

scrape_configs:
  - job_name: cumulusmx-mcp
    metrics_path: /metrics
    authorization:
      type: Bearer
      credentials: <MCP_AUTH_TOKEN_READONLY>
    static_configs:
      - targets: ["cumulusmx-mcp:8000"]

Useful alerts: cumulusmx_mcp_cumulus_up == 0 for 5 minutes (station or network down), increase(cumulusmx_mcp_writes_total{resultado="denegado"}[1h]) > 0 (someone tried to write with a read-only token). Counters live in memory and restart from zero with the process, which Prometheus handles natively.

Versioning and releases

The project follows Semantic Versioning and keeps a CHANGELOG. The version is defined once, in cumulusmx_mcp/__init__.py (__version__), and is reported by GET /health, the server_status tool, cumulusmx-mcp --version and the startup log.

To cut a release:

1. Update __version__ and add a ## [X.Y.Z] section at the top of CHANGELOG.md; also update metadata.version in the skill's SKILL.md (tests/test_versioning.py fails if they differ).
2. Merge to main (publishes the latest Docker image).
3. Run the Release workflow (Actions -> Release -> Run workflow, version X.Y.Z), or push the tag yourself (git tag vX.Y.Z && git push origin vX.Y.Z). It validates the version, creates the tag and the GitHub release with the CHANGELOG notes, publishes the X.Y.Z, X.Y, X and latest multi-architecture images to Docker Hub and, once PyPI trusted publishing is set up (see CONTRIBUTING.md), uploads the package to PyPI.

CI (.github/workflows/tests.yml) runs on every pull request and on pushes to any branch except main: lint, the test suite on Python 3.10 / 3.12 / 3.13 with FastMCP 3.x and 4.x (coverage must stay above 90 %), a build check of the package, smoke tests of the Docker image (amd64 and emulated arm64) and an informational dependency audit. Dependencies are pinned in requirements.txt and kept up to date by Dependabot.

Building locally

docker build -t cumulusmx-mcp .
docker run -d -p 8000:8000 -e MCP_AUTH_TOKEN=secret -e CUMULUSMX_URL=http://cumulusmx:8998 -v cumulus-mcp:/data cumulusmx-mcp

Docker Hub

edudele/cumulusmx-mcp

Images are built and pushed automatically on every push to main.

License

MIT