Lets an AI client look up U.S. Census American Community Survey data including income, demographics, housing, and education by ZIP code.
Also known as mcpwright/census-mcp, census-mcp, mcpwright-census
- Stars
- 0
- Tools
- —
- Downloads, 30 days
- 158
- Latest version
- 0.1.3
- Last commit
- Aug 20, 2026
- License
- MIT
What is Census (ACS by ZIP) MCP?
Census (ACS by ZIP) lets an AI client look up U.S. Census American Community Survey data including income, demographics, housing, and education by ZIP code.
Summary generated from the project's README
About Census (ACS by ZIP) MCP server
Accessing American Community Survey data for specific locations is what this server enables for developers using AI clients. It provides detailed demographic, income, housing, and education statistics for any U.S. ZIP code. Users can retrieve median household income, median home values, or educational attainment percentages for adults through a set of eight specialized tools.
This server operates locally on your machine after a one-time bulk download of the ACS 5-year release dataset. You must provide a free Census API key via the CENSUS_API_KEY environment variable to perform the initial setup. Once the data is stored in a local SQLite database, all subsequent queries are served offline for instant results.
Beyond simple lookups, the server includes a reverse lookup tool to find ZIP codes within a specific city or town. It also allows for ranking multiple ZIP codes against one another based on specific metrics like age or income. This makes it a useful resource for researchers or developers building agents that require verified U.S. Census Bureau estimates.
Written from the project's README. Every use case is checked against a quote from it.
How to install Census (ACS by ZIP) MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Census (ACS by ZIP) MCP in Claude Code
$ claude mcp add --env 'CENSUS_API_KEY=<CENSUS_API_KEY>' census-mcp -- uvx mcpwright-censusInstall Census (ACS by ZIP) MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"census-mcp": {
"command": "uvx",
"args": [
"mcpwright-census"
],
"env": {
"CENSUS_API_KEY": "<CENSUS_API_KEY>"
}
}
}
}Install Census (ACS by ZIP) MCP in VS Code
.vscode/mcp.json
{
"servers": {
"census-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"mcpwright-census"
],
"env": {
"CENSUS_API_KEY": "<CENSUS_API_KEY>"
}
}
}
}Install Census (ACS by ZIP) MCP in VS Code CLI
$ code --add-mcp '{"name":"census-mcp","type":"stdio","command":"uvx","args":["mcpwright-census"],"env":{"CENSUS_API_KEY":"<CENSUS_API_KEY>"}}'Install Census (ACS by ZIP) MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"census-mcp": {
"command": "uvx",
"args": [
"mcpwright-census"
],
"env": {
"CENSUS_API_KEY": "<CENSUS_API_KEY>"
}
}
}
}Install Census (ACS by ZIP) MCP in Codex
$ codex mcp add census-mcp --env 'CENSUS_API_KEY=<CENSUS_API_KEY>' -- uvx mcpwright-censusInstall Census (ACS by ZIP) MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.census-mcp] command = "uvx" args = ["mcpwright-census"] [mcp_servers.census-mcp.env] CENSUS_API_KEY = "<CENSUS_API_KEY>"
Install Census (ACS by ZIP) MCP in Gemini CLI
$ gemini mcp add -s user -e 'CENSUS_API_KEY=<CENSUS_API_KEY>' census-mcp uvx -- mcpwright-censusInstall Census (ACS by ZIP) MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"census-mcp": {
"command": "uvx",
"args": [
"mcpwright-census"
],
"env": {
"CENSUS_API_KEY": "<CENSUS_API_KEY>"
}
}
}
}Configuration
CENSUS_API_KEYRequiredFree Census API key (get one at https://api.census.gov/data/key_signup.html). Required for the one-time bulk download of the ACS dataset.
| Name | Description | |
|---|---|---|
| CENSUS_API_KEY | Free Census API key (get one at https://api.census.gov/data/key_signup.html). Required for the one-time bulk download of the ACS dataset. | Required |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablemcpwright/census-mcp is public and reachablegithub.com/mcpwright/census-mcp ↗Pass
- Package names this repository as its sourcemcpwright-census names mcpwright/census-mcp as sourcepypi.org/project/mcpwright-census/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-20github.com/mcpwright/census-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from mcpwright-censusPass
- No critical advisory in the package or its dependencies38 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubcensus-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 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.
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 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.
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_demographicsage 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
Census (ACS by ZIP) MCP questions
How do I add Census (ACS by ZIP) MCP to Claude Code?
Run claude mcp add --env 'CENSUS_API_KEY=<CENSUS_API_KEY>' census-mcp -- uvx mcpwright-census in your terminal. Add --scope user to make it available in every project.
How do I add Census (ACS by ZIP) MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Does this server require an API key?
Yes, a free Census API key is required for the one-time bulk download of the ACS dataset.
Is the data available offline?
Yes, the server bulk-downloads the data into a local SQLite store so that subsequent lookups are served offline and instantly.
Can I find ZIP codes for a specific city?
Yes, the find_zips tool allows you to perform a reverse lookup to find ZIPs within a city, town, or CDP.
Does the server collect my personal data?
No, the server runs entirely on your machine and does not collect, store, or transmit any personal data.