# us-open-stats-mcp

MCP server exposing normalized **Census**, **BLS**, **FRED**, and **HUD** tools. Returns small typed JSON snapshots suitable for editors and CLI clients.

Live infographics (embeddable): [us-open-stats-mcp.pages.dev](https://us-open-stats-mcp.pages.dev/)

## Install

```bash
uv sync --extra dev
./scripts/smoke.sh
```

## Run

```bash
uv run us-open-data-mcp serve
uv run python scripts/build_demo_site.py
uv run pytest -q
```

Demo UI: `cd site && python3 -m http.server 8789`

### Infographics app

Premium Vite + React + ECharts reports live in `web/`. Build emits into `site/` (Fraunces + Archivo, donut/hbar/lollipop/scatter/line charts, filterable listings, `/embed/:id` iframes).

```bash
cd web && npm install && npm run build
# or
uv run python scripts/build_demo_site.py
```

### Example MCP client config

```json
{
  "mcpServers": {
    "us-open-stats": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/us-open-stats-mcp", "us-open-data-mcp", "serve"]
    }
  }
}
```

## Tools (MVP)

| Tool | Agency |
|------|--------|
| `get_cbsa_population` | Census ACS |
| `get_hud_fmr` | HUD |
| `get_unemployment_rate` | BLS |
| `get_cpi` | BLS |
| `get_fred_series` | FRED |

Default responses use recorded fixtures so CI stays offline. Live API keys can be added later without changing tool names.

## License

MIT — see `LICENSE`.