Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@census-mcp Show me income data for 98105"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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: published (v0.1.2) —
uvx mcpwright-census(PyPI) and listed in the official MCP Registry asio.github.mcpwright/census-mcp. All 8 tools below are live and unit-tested, verified end-to-end against the live ACS 5-year release (vintage 2024 at the time of writing — the server auto-detects the latest). Part of the mcpwright suite.
Tool | What it does |
| Confirm a ZIP maps to a Census ZCTA; returns name, total population, and the ACS vintage. |
| Median household income, per-capita income, total households, and the % of households earning $200k+. |
| Total population and median age. |
| Median home value, median gross rent, occupied units, and % owner-occupied. |
| Of adults 25+, the % with a bachelor's degree or higher and the % with a graduate/professional degree. |
| Rank several ZIPs by one metric (income, age, home value, attainment, …), highest first. |
| Escape hatch: the raw value of any stored ACS variable, by code or friendly name. |
| 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).
Related MCP server: ZipExplore MCP Server
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 storeclaude mcp add census -e CENSUS_API_KEY=your-free-key -- uvx mcpwright-censusAdd 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 setupahead of time, or let the server download lazily on first use.mcpwright-census refreshre-pulls when a new ACS vintage is published. Override the store location withCENSUS_MCP_STORE.
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 Inspectorlookup_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
census-mcp runs entirely on your machine and collects, stores, or transmits no personal
data — no accounts, no tracking, no telemetry. Its only outbound requests go to the public
U.S. Census Bureau to download public data: api.census.gov for the ACS dataset (using
your own CENSUS_API_KEY), and www2.census.gov for the place-lookup file used by
find_zips (no key needed). The key is read from your environment and is never logged or sent
anywhere else. These downloads happen during setup/refresh (or lazily on first use); after
that, lookups are served from a local store with no further network calls. The downloaded data
lives under your OS cache directory (public reference data only) and can be deleted at any time.
Full policy: https://mcpwright.com/privacy
Questions, ideas, or "could it do X?" → Discussions
Bugs & concrete feature requests → Issues
Contributions welcome.
Part of mcpwright · built by Devender Gollapally
Rank several ZIPs by a single metric, highest value first.
`zips`: a list of 5-digit US ZIPs to compare. `metric`: one of
`population`, `median_age`, `median_household_income`, `per_capita_income`,
`households_200k_plus_pct`, `median_home_value`, `median_gross_rent`,
`owner_occupied_pct`, `bachelors_plus_pct`, `graduate_or_professional_pct`.
Returns each ZIP's value, sorted descending; ZIPs with no data (suppressed
or no ZCTA) are listed last. All values are ACS 5-year estimates.
Inputs: zips (required), metric (required). Returns: Several ZIPs ranked by one metric, highest value first.
Reverse lookup: the ZIPs (ZCTAs) that fall within a named place.
`place`: a U.S. place name — an incorporated city/town or a census-designated
place (e.g. 'Cambridge', 'West Hollywood'); the Census descriptor is optional
('Cambridge' and 'Cambridge city' both work). `state`: optional 2-letter USPS
code or full state name to disambiguate (many places share a name). Returns
the ZCTAs intersecting that place, ranked by `coverage_pct` — the share of
each ZCTA's land that lies within the place. This is approximate: ZCTAs don't
nest inside places, so a ZIP may span several places and vice versa. Built on
the public 2020 Census ZCTA-to-Place relationship file (no API key needed).
Inputs: place (required), state. Returns: ZIPs intersecting a named place, best land coverage first.
Raw value of a single ACS variable for a ZIP — an escape hatch.
`zip_code`: a 5-digit US ZIP. `variable`: an ACS variable code (e.g.
`B19013_001E`) or the friendly store-column name (e.g.
`median_household_income`); both match case-insensitively. Returns that one
value for the ZIP. Limited to the variables held in the local store (the
same ones the other tools draw on); an unknown variable errors with the
full list.
Inputs: variable (required), zip_code (required). Returns: The raw value of a single ACS variable for a ZIP / ZCTA.
Population and median age for a ZIP.
`zip_code`: a 5-digit US ZIP. Returns the total population and the median
age of residents — both ACS 5-year estimates. (Age-bracket breakdowns,
e.g. under-18 / 18-34 / 35-64 / 65+, are on the roadmap.)
Inputs: zip_code (required). Returns: Population and age for a ZIP / ZCTA.
Educational attainment for a ZIP: % bachelor's+ and % graduate degree.
`zip_code`: a 5-digit US ZIP. Of the population aged 25 and over, returns
the percent with a bachelor's degree or higher and the percent with a
graduate or professional degree — ACS 5-year estimates.
Inputs: zip_code (required). Returns: Educational attainment among the 25-and-older population of a ZIP / ZCTA.
Housing measures for a ZIP: home value, rent, and owner-occupied share.
`zip_code`: a 5-digit US ZIP. Returns the median value of owner-occupied
homes, the median gross rent (monthly), the number of occupied housing
units, and the percent that are owner-occupied — all ACS 5-year estimates.
Note: ACS top-codes median home value at $2,000,001, so the priciest ZIPs
(e.g. Atherton 94027) report exactly that — read it as "$2M or more," not an
exact value.
Inputs: zip_code (required). Returns: Housing measures for a ZIP / ZCTA (all dollar amounts in USD).
Income measures for a ZIP: median household, per-capita, and % $200k+.
`zip_code`: a 5-digit US ZIP. Returns median household income, per-capita
income, the number of households, and the percent of households earning
$200k+ — all ACS 5-year estimates in USD. Note: ACS top-codes median
household income at $250,001, so the wealthiest ZIPs (e.g. Atherton 94027)
report exactly that — read it as "$250k or more," not an exact figure.
Inputs: zip_code (required). Returns: Income measures for a ZIP / ZCTA (all dollar amounts in USD).
Confirm a ZIP maps to a Census ZCTA and return its name and population.
`zip_code`: a 5-digit US ZIP. A good first call to validate a ZIP before
asking for more detail. Returns the ZCTA, Census area name, total population,
and the ACS data vintage. ZIP ≈ ZCTA; ~2% of ZIPs have no ZCTA and error.
Inputs: zip_code (required). Returns: Basic identity and size for a ZIP / ZCTA.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Scored across 8 tools
Each tool has a clearly distinct purpose: validation, metric-specific lookups, comparison, reverse lookup, and raw ACS access. There is no overlap or ambiguity between them.
All tool names follow a consistent verb_noun snake_case pattern (lookup_zip, get_income, compare_zips, etc.). No mixed styles or vague verbs.
8 tools is well-scoped for a census data server. Each tool covers a meaningful aspect of the domain without bloat or redundancy.
The set covers core census data needs: validation, income, demographics, housing, education, comparison, reverse lookup, and raw variable access. Minor gaps like age-bracket breakdowns exist but are noted as roadmap, and the raw access tool mitigates many limitations.
US ZIP code intelligence: demographics, weather, tax, crime, housing, voting, and more.
Query US Census Bureau data: demographics, economics, and housing statistics.
Ziplore: US ZIP to county, FIPS, time zone, Census demographics; radius and city ZIPs. Free, no key.
Ziplore: US ZIP to county, FIPS, time zone, Census demographics; radius and city ZIPs. Free, no key.
