mcpwright.

census-mcp

Any ZIP, fully profiled.

An MCP server that lets an LLM profile any U.S. ZIP code — income, demographics, housing, and education — straight from the Census Bureau's American Community Survey. Read-only, all public data, bulk-downloaded once then served instantly offline.

See it in action

One prompt in Claude Code, start to finish:

Using census, compare ZIPs 94027, 10021, and 90069 by household income — which is wealthiest, and what's it actually like there?

What happened

  1. Claude called compare_zips(["94027","10021","90069"], "median_household_income") — ranked highest-first: 94027 ($250k+), 10021 Upper East Side ($158,677), 90069 West Hollywood ($107,987).
  2. It profiled the leader with get_income, get_housing, and get_education: Atherton, CA — per-capita income $188,761, 65.6% of households earning $200k+, a $2M+ median home value, 87.6% owner-occupied, and 83.2% of adults holding a bachelor's degree or higher (52.2% a graduate degree).
  3. It flagged the honest caveat: $250,001 and $2,000,001 are the ACS top-codes (the Census cap), not exact figures — Atherton simply runs past the top of the scale.

Every figure comes from the local ACS store the server built on first run — not the model's memory.

What you can ask

Real exchanges, driven entirely by the tools below.

How wealthy is ZIP 94027, really?

Resolves Atherton, CA: median household income hits the ACS cap of $250,001, per-capita income is $188,761, and 65.6% of its 2,236 households earn $200k+ — with the note that $250,001 is a top-code, not an exact number.

Rank 94027, 10021, 60601, and 90069 by income.

Returns them highest-first: Atherton $250k+, Upper East Side $158,677, Chicago's Loop $121,458, West Hollywood $107,987 — one metric, several ZIPs, sorted.

What are the ZIP codes for Cambridge, Massachusetts?

Reverse lookup: returns 02139, 02141, 02142, 02140, 02138 — each ~100% inside the city — plus 02472 at just 0.7% (it's mostly Watertown), ranked by how much of each ZIP's land lies in the place. Pass a state to disambiguate same-named towns.

Tell me about housing and schooling around MIT (02139).

Pulls median home value, gross rent, and owner-occupied share from get_housing, and from get_education: of ~26,700 adults 25+, 79.5% hold a bachelor's degree or higher and 49% a graduate degree.

Tools

ToolWhat it does
lookup_zipConfirm a ZIP maps to a Census ZCTA; returns name, total population, and the ACS vintage.
get_incomeMedian household income, per-capita income, households, and % earning $200k+.
get_demographicsTotal population and median age.
get_housingMedian home value, median gross rent, occupied units, and % owner-occupied.
get_educationOf adults 25+, the % with a bachelor's+ and the % with a graduate/professional degree.
compare_zipsRank several ZIPs by one metric (income, age, home value, attainment, …), highest first.
find_zipsReverse lookup: the ZIPs within a city/town, ranked by how much of each ZIP's land lies there.
get_acs_variableEscape hatch: the raw value of any stored ACS variable, by code or friendly name.

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

Install

Requires Python 3.12+, uv, and a free Census API key (instant — it's only needed for the one-time bulk download).

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" }
    }
  }
}

OpenAI & other MCP clients

It's a standard stdio MCP server — so it works beyond Claude: the OpenAI Agents SDK, Cursor, VS Code, Cline, Goose, Zed, and more all launch it the same way (pass CENSUS_API_KEY in the environment).

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

The first run downloads the full ACS dataset (~33k ZCTAs) into a local SQLite store, so every later lookup is instant and offline — no per-query network calls, no rate limits. mcpwright-census refresh re-pulls when a new ACS vintage drops; the key is needed only for those downloads.

Source, full tool reference, and roadmap → github.com/mcpwright/census-mcp

Questions or ideas? → Discussions  ·  found a bug? → Issues