Metadata-Version: 2.5
Name: medicaid-mcp
Version: 0.1.1
Summary: An MCP server wrapping the data.medicaid.gov API so Claude and other MCP clients can explore US Medicaid and CHIP open data.
Project-URL: Homepage, https://annalulushi.com/projects/medicaid-mcp/
Author-email: Anna Lulushi <annalulushi@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: chip,cms,dkan,mcp,medicaid,nadac,open-data
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.12
Requires-Dist: httpx>=0.28.1
Requires-Dist: mcp<2.3,>=2.2.0
Requires-Dist: pydantic>=2.13.5
Requires-Dist: uvicorn>=0.54.0
Description-Content-Type: text/markdown

# medicaid-mcp

An MCP server that lets Claude, or any MCP client, explore US Medicaid and CHIP open data from
[data.medicaid.gov](https://data.medicaid.gov) and the Medicaid datasets CMS publishes on
[data.cms.gov](https://data.cms.gov). It runs on your own computer, reads only public data, and
needs no account or API key.

Ask things like "How has Ohio's Medicaid enrollment changed over the last year?", "What have
pharmacies paid for metformin lately?" or "Which datasets were updated this month?"

Setup instructions are also on the [docs page](https://annalulushi.com/projects/medicaid-mcp/).

## Install

Install [uv](https://docs.astral.sh/uv/) (`curl -LsSf https://astral.sh/uv/install.sh | sh` on macOS or Linux). Then run the server once in a terminal, so the first download doesn't happen while your client waits. Press Ctrl-C to stop it.

```bash
uvx medicaid-mcp@0.1.1
```

**Claude Code:**

```bash
claude mcp add --scope user medicaid -- uvx medicaid-mcp@0.1.1
```

**Claude Desktop:** add this to `claude_desktop_config.json` (**Settings → Developer → Edit Config**), then restart. Desktop apps don't get your shell's `PATH`, so use the full path that `which uvx` prints.

```json
{
  "mcpServers": {
    "medicaid": {
      "command": "/absolute/path/to/uvx",
      "args": ["medicaid-mcp@0.1.1"]
    }
  }
}
```

**Other MCP clients:** any client that launches stdio servers works. The command is `uvx` and the argument is `medicaid-mcp@0.1.1`. claude.ai on the web isn't supported, because it needs a hosted URL. So far this has been tested on macOS only.

**Updating:** replace `0.1.1` in your config with the newest version on [PyPI](https://pypi.org/project/medicaid-mcp/).

## What it does

A server over two open, unauthenticated CMS APIs:

- **data.medicaid.gov**, the primary source, covering its whole catalog.
- **data.cms.gov**, limited to three Medicaid datasets that live only there: Medicaid Spending by Drug, Medicaid Opioid Prescribing Rates, and Medicaid Managed Care service utilization. Their dataset ids are prefixed `cms:`. Medicare program data is out of scope.

It is distinct from Anthropic's [CMS Coverage connector](https://academy.claude.com/tutorials/using-the-cms-coverage-connector-in-claude), which covers Medicare Part B coverage policy (NCDs/LCDs, billing articles). The two are complementary: whether Medicare covers a drug there, what Medicaid pays for it (NADAC) here.

### General tools

| Tool                   | Purpose                                                            |
| ---------------------- | ------------------------------------------------------------------ |
| `search_datasets`      | Search the catalog by query, publisher, keyword, or theme.         |
| `get_dataset`          | Full metadata for one dataset, plus a synthesized `columns` array. |
| `list_dataset_columns` | Just the columns — the cheap orientation call.                     |
| `query_dataset`        | Filter, select, sort, and paginate rows via a friendly filter DSL. |

The usual pattern is `search_datasets` → `list_dataset_columns` → `query_dataset`, or one of the shortcuts below.

### Shortcuts for common questions

1. `get_state_enrollment_snapshot` — recent monthly Medicaid/CHIP enrollment for one state.
2. `compare_states_enrollment_trend` — multi-state trend, shaped for summarization or charting.
3. `get_state_eligibility_renewals` — renewal/termination churn.
4. `get_drug_price_nadac` — National Average Drug Acquisition Cost lookups.
5. `get_state_drug_utilization` — units, prescriptions, and amounts reimbursed.
6. `get_managed_care_enrollment` — enrollment by plan and program type.
7. `get_quality_measures` — Child/Adult Core Set performance measures.
8. `whats_new_medicaid` — recently modified datasets.
9. `get_medicaid_drug_spending` — Medicaid spending, claims, and units by drug, 2020–2024 (data.cms.gov).
10. `get_opioid_prescribing_rates` — Medicaid opioid prescribing rates by state and plan type (data.cms.gov).

### How it handles the data

- Results are the published figures, with notes on the rules applied (e.g. updated months preferred over preliminary ones).
- Suppressed values (`NR`, `DS`, `*`, nulls) are passed through as published, never turned into zero.
- Most numeric-looking columns are published as text, which compares as text (`"9" > "10"`). Range filters (`<`, `>`) are refused on those columns rather than returning wrong rows.
- Unknown column names, operators and arguments are errors, never silently ignored. Every error says what to call next.
- The data is only as current as what the agencies publish. Most datasets update monthly or yearly.

## Configuration

Optional environment variables. None are secrets — the upstream APIs are open.

| Variable                        | Default                     | Purpose                                                       |
| ------------------------------- | --------------------------- | ------------------------------------------------------------- |
| `MEDICAID_MCP_BASE_URL`         | `https://data.medicaid.gov` | Upstream API root                                             |
| `MEDICAID_MCP_CMS_BASE_URL`     | `https://data.cms.gov`      | data.cms.gov root, for the `cms:` registry datasets           |
| `MEDICAID_MCP_TIMEOUT`          | `30`                        | Request timeout, seconds                                      |
| `MEDICAID_MCP_CACHE_TTL_SEARCH` | `900`                       | Search-result cache lifetime, seconds                         |
| `MEDICAID_MCP_CACHE_TTL_META`   | `3600`                      | Dataset-metadata cache lifetime, seconds                      |
| `MEDICAID_MCP_LOG_LEVEL`        | `INFO`                      | Log level                                                     |
| `PORT`                          | `8000`                      | HTTP listen port; unprefixed because hosting platforms set it |

Row data is never cached.

## License

[MIT](https://opensource.org/license/mit) — free to use, modify, and redistribute, including commercially. Copyright (c) 2026 Anna Lulushi.
