mcpwright-census 0.1.0

MCP server for U.S. Census (ACS) data by ZIP code — income, age, housing, education — served from a local store. Needs a free Census API key.

census-mcp

U.S. Census data by ZIP code, inside your agent. An MCP server that lets an LLM look up income, demographics, housing, and education for any ZIP — built on Anthropic's official mcp Python SDK.

All tools are read-only. Data is the U.S. Census Bureau's American Community Survey (ACS) 5-year release — bulk-downloaded once into a local store, then served offline. A free Census API key is required for the one-time download.

Status: all 8 tools below are live and unit-tested, and the server has been verified end-to-end against the live ACS 5-year release (vintage 2024 at the time of writing — the server auto-detects the latest). PyPI + MCP Registry publish is the next step. Part of the mcpwright suite.

Tools

Tool	What it does
lookup_zip(zip_code)	Confirm a ZIP maps to a Census ZCTA; returns name, total population, and the ACS vintage.
get_income(zip_code)	Median household income, per-capita income, total households, and the % of households earning $200k+.
get_demographics(zip_code)	Total population and median age.
get_housing(zip_code)	Median home value, median gross rent, occupied units, and % owner-occupied.
get_education(zip_code)	Of adults 25+, the % with a bachelor's degree or higher and the % with a graduate/professional degree.
compare_zips(zips, metric)	Rank several ZIPs by one metric (income, age, home value, attainment, …), highest first.
get_acs_variable(zip_code, variable)	Escape hatch: the raw value of any stored ACS variable, by code or friendly name.
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.

ZIP ≈ ZCTA (ZIP Code Tabulation Area): they mostly coincide, but ~2% of ZIPs (PO-box-only / non-residential) have no ZCTA and will return an error. All ACS figures are 5-year estimates.

find_zips is the reverse direction (place → ZIPs). It's approximate: ZCTAs don't nest inside places, so a ZIP can span several places and vice versa — read each match's coverage_pct and pass a state to disambiguate same-named places (e.g. Cambridge, MA vs OH). It's built on the public 2020 Census ZCTA-to-Place relationship file (2020 geography; no API key needed for it).

Install

Requires Python 3.12+ and a free Census API key (set CENSUS_API_KEY). The PyPI package is mcpwright-census; the command, server, and tools are all "census".

export CENSUS_API_KEY=your-free-key
uvx mcpwright-census setup     # one-time: bulk-download the ACS dataset into a local store

Claude Code

claude mcp add census -e CENSUS_API_KEY=your-free-key -- uvx mcpwright-census

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "census": {
      "command": "uvx",
      "args": ["mcpwright-census"],
      "env": { "CENSUS_API_KEY": "your-free-key" }
    }
  }
}

First run downloads the full ACS dataset (~33k ZCTAs) into a local SQLite store under your OS cache dir, so every later lookup is instant and offline. Run mcpwright-census setup ahead of time, or let the server download lazily on first use. mcpwright-census refresh re-pulls when a new ACS vintage is published. Override the store location with CENSUS_MCP_STORE.

Develop

git clone https://github.com/mcpwright/census-mcp && cd census-mcp
uv sync
uv run pytest -v                                     # tests (mocked Census + seeded SQLite)
uv run ruff check src/ && uv run ruff format --check src/   # lint + format
uv run mypy                                          # type checking
uv run mcp dev src/census_mcp/server.py              # poke the tools in the MCP Inspector

Roadmap

• lookup_zip — validate a ZIP, name + population
• get_income — income measures + % $200k+
• get_demographics — population + median age (age brackets still to come)
• get_housing — median home value, rent, % owner-occupied
• get_education — % bachelor's+, % graduate
• compare_zips — one metric across several ZIPs, ranked
• get_acs_variable — raw value for any stored ACS variable (escape hatch)
• find_zips — reverse lookup: place → ZIPs, ranked by land coverage
• get_demographics age brackets (under-18 / 18-34 / 35-64 / 65+)
• Publish to PyPI (mcpwright-census) + the official MCP Registry

Questions & feedback

• Questions, ideas, or "could it do X?" → Discussions
• Bugs & concrete feature requests → Issues

Contributions welcome.

---

Part of mcpwright · built by Devender Gollapally