{
  "markdown": "# census-mcp\n\n<!-- mcp-name: io.github.mcpwright/census-mcp -->\n\n**U.S. Census data by ZIP code, inside your agent.** An [MCP](https://modelcontextprotocol.io)\nserver that lets an LLM look up income, demographics, housing, and education for any ZIP —\nbuilt on Anthropic's official [`mcp` Python SDK](https://github.com/modelcontextprotocol/python-sdk).\n\nAll tools are **read-only**. Data is the U.S. Census Bureau's American Community Survey (ACS)\n5-year release — **bulk-downloaded once into a local store**, then served offline. A free\nCensus API key is required for the one-time download.\n\n> Status: published (v0.1.2) — `uvx mcpwright-census` (PyPI) and listed in the official MCP\n> Registry as `io.github.mcpwright/census-mcp`. All 8 tools below are live and unit-tested, verified\n> end-to-end against the live ACS 5-year release (vintage 2024 at the time of writing — the\n> server auto-detects the latest). Part of the\n> [**mcpwright**](https://github.com/mcpwright) suite.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `lookup_zip(zip_code)` | Confirm a ZIP maps to a Census ZCTA; returns name, total population, and the ACS vintage. |\n| `get_income(zip_code)` | Median household income, per-capita income, total households, and the % of households earning $200k+. |\n| `get_demographics(zip_code)` | Total population and median age. |\n| `get_housing(zip_code)` | Median home value, median gross rent, occupied units, and % owner-occupied. |\n| `get_education(zip_code)` | Of adults 25+, the % with a bachelor's degree or higher and the % with a graduate/professional degree. |\n| `compare_zips(zips, metric)` | Rank several ZIPs by one metric (income, age, home value, attainment, …), highest first. |\n| `get_acs_variable(zip_code, variable)` | Escape hatch: the raw value of any stored ACS variable, by code or friendly name. |\n| `find_zips(place, state=None)` | Reverse lookup: the ZIPs that fall within a city/town/CDP, ranked by how much of each ZIP's land lies in the place. |\n\nZIP ≈ ZCTA (ZIP Code Tabulation Area): they mostly coincide, but ~2% of ZIPs (PO-box-only /\nnon-residential) have no ZCTA and will return an error. All ACS figures are 5-year *estimates*.\n\n`find_zips` is the reverse direction (place → ZIPs). It's approximate: ZCTAs don't nest inside\nplaces, so a ZIP can span several places and vice versa — read each match's `coverage_pct` and\npass a `state` to disambiguate same-named places (e.g. Cambridge, MA vs OH). It's built on the\npublic 2020 Census ZCTA-to-Place relationship file (2020 geography; no API key needed for it).\n\n## Install\n\nRequires Python 3.12+ and a free [Census API key](https://api.census.gov/data/key_signup.html)\n(set `CENSUS_API_KEY`). The PyPI package is `mcpwright-census`; the command, server, and tools\nare all \"census\".\n\n```bash\nexport CENSUS_API_KEY=your-free-key\nuvx mcpwright-census setup     # one-time: bulk-download the ACS dataset into a local store\n```\n\n### Claude Code\n\n```bash\nclaude mcp add census -e CENSUS_API_KEY=your-free-key -- uvx mcpwright-census\n```\n\n### Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"census\": {\n      \"command\": \"uvx\",\n      \"args\": [\"mcpwright-census\"],\n      \"env\": { \"CENSUS_API_KEY\": \"your-free-key\" }\n    }\n  }\n}\n```\n\n> **First run** downloads the full ACS dataset (~33k ZCTAs) into a local SQLite store under\n> your OS cache dir, so every later lookup is instant and offline. Run `mcpwright-census setup`\n> ahead of time, or let the server download lazily on first use. `mcpwright-census refresh`\n> re-pulls when a new ACS vintage is published. Override the store location with\n> `CENSUS_MCP_STORE`.\n\n## Develop\n\n```bash\ngit clone https://github.com/mcpwright/census-mcp && cd census-mcp\nuv sync\nuv run pytest -v                                     # tests (mocked Census + seeded SQLite)\nuv run ruff check src/ && uv run ruff format --check src/   # lint + format\nuv run mypy                                          # type checking\nuv run mcp dev src/census_mcp/server.py              # poke the tools in the MCP Inspector\n```\n\n## Roadmap\n\n- [x] `lookup_zip` — validate a ZIP, name + population\n- [x] `get_income` — income measures + % $200k+\n- [x] `get_demographics` — population + median age _(age brackets still to come)_\n- [x] `get_housing` — median home value, rent, % owner-occupied\n- [x] `get_education` — % bachelor's+, % graduate\n- [x] `compare_zips` — one metric across several ZIPs, ranked\n- [x] `get_acs_variable` — raw value for any stored ACS variable (escape hatch)\n- [x] `find_zips` — reverse lookup: place → ZIPs, ranked by land coverage\n- [ ] `get_demographics` age brackets (under-18 / 18-34 / 35-64 / 65+)\n- [x] Publish to PyPI (`mcpwright-census`) + the official MCP Registry\n\n## Privacy\n\ncensus-mcp runs entirely **on your machine** and collects, stores, or transmits **no personal\ndata** — no accounts, no tracking, no telemetry. Its only outbound requests go to the public\n**U.S. Census Bureau** to download public data: `api.census.gov` for the ACS dataset (using\n**your own** `CENSUS_API_KEY`), and `www2.census.gov` for the place-lookup file used by\n`find_zips` (no key needed). The key is read from your environment and is **never logged or sent\nanywhere else**. These downloads happen during `setup`/`refresh` (or lazily on first use); after\nthat, lookups are served from a local store with no further network calls. The downloaded data\nlives under your OS cache directory (public reference data only) and can be deleted at any time.\n\nFull policy: **https://mcpwright.com/privacy**\n\n## Questions & feedback\n\n- **Questions, ideas, or \"could it do X?\"** → [**Discussions**](https://github.com/mcpwright/census-mcp/discussions)\n- **Bugs & concrete feature requests** → [**Issues**](https://github.com/mcpwright/census-mcp/issues)\n\nContributions welcome.\n\n---\n\nPart of [**mcpwright**](https://github.com/mcpwright) · built by [Devender Gollapally](https://github.com/devender)\n",
  "bytes": 5946,
  "sha": "a0c6b4ca41973acc5458d955738711f8c3145e006aa581d310df796a58d4c754",
  "repo_slug": "mcpwright/census-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mcpwright_census_mcp_7b804946/readme"
}