baseline-mcp

MCP server exposing Baseline as agent tools — statistically rigorous weather and climate context, not just current conditions. Thin translation layer only: no climate logic lives here, every tool call is an HTTP request to the Baseline API. See baseline_mcp_server_plan.md in the Baseline project for the full design, and METHODOLOGY.md for how the underlying data and rankings are computed.

Tools

• get_climate_context — natural-language weather and climate questions, full context back (forecast + 35-year historical percentile ranking).
• get_context_for_coordinates — same, for an exact lat/lon rather than a place name.
• get_water_year_status — precipitation/temperature status since the start of the water year (Oct 1 US / Jan 1 elsewhere), ranked against 35 years.
• compare_to_normal — how unusual current or forecast conditions are at one location.
• compare_locations — rank precipitation, temperature, or snowfall across 2-10 locations (or a curated category like colorado_ski_resorts) in a single call, over a water year, season, month, or ski season.

Installation

Requires a Baseline API key. Self-serve signup isn't available yet — during this early period, contact Chad McNutt (chadmcnutt@gmail.com) for a key.

pip install baseline-mcp
# or: uvx baseline-mcp

Then add it to your MCP client's config, with your API key:

Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "baseline": {
      "command": "uvx",
      "args": ["baseline-mcp"],
      "env": {
        "BASELINE_API_URL": "https://api.baselinecontext.com",
        "BASELINE_API_KEY": "your-key-here"
      }
    }
  }
}

Claude Code: claude mcp add baseline --env BASELINE_API_URL=https://api.baselinecontext.com --env BASELINE_API_KEY=your-key-here -- uvx baseline-mcp

Cursor (.cursor/mcp.json or global MCP settings): same shape as the Claude Desktop config above, under whatever key Cursor's MCP settings use for server name.

Local development

The venv lives outside this directory (~/.venvs/baseline-mcp) rather than in .venv/ here, because this project sits under iCloud-synced ~/Documents — iCloud evicts/re-materializes files inside large venvs unpredictably, which causes intermittent ModuleNotFoundErrors. Keep it that way.

python3 -m venv ~/.venvs/baseline-mcp
~/.venvs/baseline-mcp/bin/pip install -e .
cp .env.example .env   # fill in BASELINE_API_URL and a free_api-tier BASELINE_API_KEY

Run against a local Baseline instance (python3 app.py in ../baseline), then:

~/.venvs/baseline-mcp/bin/mcp dev src/baseline_mcp/server.py

Status

All 5 tools built and tested against a live local Baseline instance, including tool-selection validation in Claude Desktop. Verified end-to-end against the production Baseline API as of the 2026-08-01 soft-launch prep (data freshness, temporal query handling, and climatology all fixed and confirmed live).

The Baseline API each tool wraps was additionally exercised against production the week of 2026-08-05 through a ~150-question adversarial stress-test corpus (spatial, temporal, and phrasing edge cases) — real bugs were found and fixed at every layer this server depends on: location extraction, temporal-window parsing, and geocoding, all deployed and reverified live, zero regressions.

METHODOLOGY.md (trust collateral) complete. Production now served over TLS at api.baselinecontext.com. See baseline_mcp_server_plan.md in the Baseline project for full task history. Published to PyPI as of 0.1.3.

0.1.4 (wording fix): compare_to_normal no longer suggests "this month" as a time window. Baseline declines any window beyond its 10-day forecast, so the old example steered assistants straight into a decline; the examples are now near-term windows only ("today", "tomorrow", "this weekend", "this week", "the next 10 days"), and the description says where further-out or past periods go instead. No code change to any tool.

0.1.3 (bugfix): uvx baseline-mcp (and any fresh pip install) was broken for every new install as of PyPI's mcp package reaching 2.0.0 — this project's dependency was declared as mcp[cli]>=1.28.1 with no upper bound, and 2.0.0 removed mcp.server.fastmcp, which server.py imports directly. Pinned to mcp[cli]>=1.28.1,<2.0.0. No functional changes to any tool.