cms-mcp

A read-only MCP server over the DuckDB star schema built by cms-inpatient-warehouse. It gives an agent seven typed tools for Medicare inpatient DRG data, plus one guarded SQL tool for anything the typed tools do not cover.

Read this first: the data covers 71.7% of national volume

CMS suppresses any hospital-DRG cell with fewer than 11 discharges, so the fact table does not sum to the published provider-level totals. For data year 2024, CMS published 6,904,504 discharges nationally; the mart holds 4,952,481, about 71.7%. Every number this server returns is an estimate over published cells. Small hospitals and rare DRGs are underrepresented, and no reweighting fixes this, because the suppressed values are not published at any grain.

Related MCP server: mcp-server-duckdb

Setup

1. Build the warehouse:

git clone https://github.com/abhaymettu/cms-inpatient-warehouse
cd cms-inpatient-warehouse
./run_all.sh

This produces warehouse.duckdb. Per its README, the run takes about 7 seconds after an 84 MB one-time download.

2. Install this server with uv:

uv venv
uv pip install -e .

or, without cloning this repo:

uv pip install git+https://github.com/abhaymettu/cms-mcp

3. Run it, pointed at the warehouse file:

CMS_MCP_DB=/path/to/warehouse.duckdb cms-mcp

This speaks MCP over stdio. python -m cms_mcp is equivalent to the cms-mcp binary.

Client configuration

Claude Desktop, Cursor, or any generic stdio client (claude_desktop_config.json):

{
  "mcpServers": {
    "cms-mcp": {
      "command": "/path/to/cms-mcp/.venv/bin/cms-mcp",
      "env": {
        "CMS_MCP_DB": "/path/to/warehouse.duckdb"
      }
    }
  }
}

Claude Code:

claude mcp add cms-mcp -e CMS_MCP_DB=/path/to/warehouse.duckdb -- /path/to/.venv/bin/cms-mcp

MCP Inspector, to list tools without a client:

npx @modelcontextprotocol/inspector --cli .venv/bin/cms-mcp -e CMS_MCP_DB=/path/to/warehouse.duckdb --method tools/list

See docs/client-configs.md for these plus a tools/call example, and docs/smoke-test.md for a captured Inspector session against the real warehouse: every tool called once, plus the rejection cases.

Tools

Schema

Two rules an agent must follow:

• Join facts to dim_provider on provider_sk, not ccn. dim_provider is a Type 2 dimension, so a ccn can match more than one row.

• avg_* columns are per discharge and not additive. Sum ext_* (extended amount, already multiplied by discharges), then divide, rather than averaging avg_* across rows.

Guardrails

Failure modes

• Suppression bias. Covered above. It affects every tool, not just query.

• A timed-out query returns an error, but the process keeps running. Narrow a slow analytic join rather than retrying it as-is.

• The rate limit is per server process, not per client. Two clients sharing one process share the same token bucket.

• stdio only, no auth. This is a local tool for one trusted process to talk to, not a network service.

• If the warehouse file is rebuilt while the server holds it open, the server keeps serving the old file until restarted.

• Summing avg_* columns silently gives wrong rollups. They are per discharge, not additive. Use ext_* for anything that needs to be summed.

• Joining dim_provider on ccn fans out facts by version count, because dim_provider is Type 2. Join on provider_sk instead.

• A query that hits the 1GB memory limit fails with a DuckDB out-of-memory message.

• PRAGMA statements do not work inside the row-cap wrapper, because the wrapper selects from the query as a subquery.

• The real-data tests are skipped in CI, because the warehouse file is not committed. CI proves the guardrails and tool contracts against a small fixture, not the actual numbers.

• describe_table and query cannot see the staging or intermediate schemas, by design. Only marts is exposed.

Development

uv pip install -e ".[dev]"
pytest -q
ruff check .

tests/test_real_warehouse.py runs only when CMS_MCP_DB points at a real warehouse file; otherwise it is skipped. CI runs on the small fixture built in tests/conftest.py.

Licence

MIT.