Census (ACS by ZIP)

io.github.mcpwrightPublished by GitHub account mcpwrightv0.1.3Updated Oct 24, 2026

U.S. Census (ACS) data by ZIP: income, demographics, housing, education, from a local store.

VerifiedSTDIODesktop onlyLocation & LifestyleData & Analytics

Overview

AI-generated overview

Lets an assistant look up U.S. Census ACS income, demographic, housing, and education figures for any ZIP code from a local offline store.

What you can do
Provides eight read-only tools over American Community Survey 5-year data: lookup_zip confirms a ZIP maps to a Census ZCTA and returns population and vintage; get_income, get_demographics, get_housing, and get_education return median household income, median age, home value and rent, and educational attainment. compare_zips ranks several ZIPs by one metric, get_acs_variable returns any stored ACS variable by code or friendly name, and find_zips does a reverse place-to-ZIP lookup ranked by coverage percentage.
When to use it
Useful when an assistant needs U.S. neighborhood-level statistics by ZIP code, such as comparing income or housing costs across areas, profiling a location, or resolving which ZIPs fall inside a city. It is a good fit when repeated lookups are expected, since data is downloaded once and then served locally without further network calls.
Requirements
Runs locally as a Python package (mcpwright-census) via uvx; requires Python 3.12+ and a free Census API key supplied in the CENSUS_API_KEY environment variable. A one-time setup or refresh command bulk-downloads the ACS dataset into a local SQLite store under the OS cache directory; the store location can be overridden with CENSUS_MCP_STORE. Network access to Census Bureau hosts is needed only for the initial download and refresh.
Before you install
The CENSUS_API_KEY environment variable is required and is used for the one-time bulk download; the README states it is never logged or sent anywhere else. Outbound requests go only to public Census Bureau endpoints during setup or refresh. All tools are read-only and no personal data is collected, but figures are 5-year estimates, roughly 2% of ZIPs have no ZCTA and return an error, and find_zips results are approximate and should be read with the coverage percentage.

Installation

In SourceWeft

  1. Open Census (ACS by ZIP) in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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: published (v0.1.2) — uvx mcpwright-census (PyPI) and listed in the official MCP Registry as io.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.

Tools

ToolWhat 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".

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

Claude Code

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

Claude Desktop

Add to claude_desktop_config.json:

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

bash
git clone https://github.com/mcpwright/census-mcp && cd census-mcpuv syncuv run pytest -v                                     # tests (mocked Census + seeded SQLite)uv run ruff check src/ && uv run ruff format --check src/   # lint + formatuv run mypy                                          # type checkinguv 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

Privacy

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 & feedback

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

Contributions welcome.

Part of mcpwright · built by Devender Gollapally

Source: README.md at commit 73cc534

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.3LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts