Click on "Install 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: Census API 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.
| Name | Required | Description | Default |
|---|---|---|---|
| zips | Yes | ||
| metric | Yes |
| Name | Required | Description |
|---|---|---|
| metric | Yes | The compared metric's name |
| results | Yes | One entry per requested ZIP, sorted by value descending; ZIPs with no value are listed last |
| vintage | Yes | ACS 5-year data vintage (end year) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, and the description adds valuable behavioral details: results are sorted descending, ZIPs with missing data are listed last, and values are ACS 5-year estimates. This goes beyond the annotations and helps the agent understand output ordering and data provenance.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact yet information-dense. It front-loads the core purpose in one sentence, then efficiently documents parameters and behavioral details in a bullet-like list embedded in prose. Every sentence adds value, with no fluff or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, the description need not explain return format, and it wisely covers the essential behavioral aspects: sorting, missing-data handling, and the metric enum. It is slightly less explicit about when to prefer this over sibling tools, but it is complete enough for an agent to use it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description fully compensates: it defines 'zips' as a list of 5-digit US ZIPs and provides the complete list of allowed values for 'metric'. Without this, the agent would have no idea what values are valid or what each parameter means.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb ('Rank') and resource ('several ZIPs'), immediately distinguishing it from sibling tools that operate on single ZIPs or specific metrics. It also enumerates the exact metrics, leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly indicates the tool is for comparing multiple ZIPs on a single metric, which provides strong contextual guidance. It does not explicitly name alternatives or exclusion criteria, but the sibling list and the phrase 'several ZIPs' imply when this tool is appropriate versus single-lookup tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| place | Yes | ||
| state | No |
| Name | Required | Description |
|---|---|---|
| query | Yes | The place name searched for |
| state | No | The 2-letter USPS state filter applied, if any |
| matches | Yes | ZCTAs intersecting the place, sorted by coverage_pct descending. Empty places (no match) raise an error instead. |
| vintage | Yes | Census geography year of the ZCTA-to-place relationship (2020) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint and openWorldHint, but the description adds valuable context beyond those: the approximate nature of ZCTA/place relationships, the ranking by coverage_pct, and the data source. It also clarifies that no API key is needed. This enriches the behavioral understanding without contradicting the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and front-loaded: the opening sentence states the core function, followed by parameter details, ranking, caveats, and data source in a logical flow. Every sentence contributes value, and the length is appropriate for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity and the presence of an output schema, the description covers all necessary aspects: purpose, parameters, output ranking, limitations (approximate), and data provenance. It is complete for an agent to select and invoke the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates by explaining both parameters in detail: place is a named US city/town/CDP with examples, and state is optional with formats. It also clarifies the meaning of coverage_pct in relation to the output, which goes beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Reverse lookup: the ZIPs (ZCTAs) that fall within a named place.' This clearly distinguishes it from sibling tools like lookup_zip (which presumably does the forward lookup) and other data tools. The purpose is unambiguous and specific.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear context for when to use the tool: when you have a U.S. place name and need the intersecting ZCTAs. It notes that state disambiguates, implying when to supply that parameter. However, it does not explicitly contrast with alternatives or mention when not to use this tool, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| variable | Yes | ||
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| name | No | Census name for the area |
| zcta | Yes | 5-digit ZIP Code Tabulation Area |
| value | No | The variable's value for this ZIP, or null if missing/suppressed (a string only for the 'name' variable) |
| column | Yes | Friendly store-column name, e.g. 'median_household_income' |
| vintage | Yes | ACS 5-year data vintage (end year) |
| variable | Yes | ACS variable code, e.g. 'B19013_001E' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description directly contradicts the openWorldHint annotation by stating it is 'Limited to the variables held in the local store.' This is a clear closed-world claim, whereas openWorldHint implies the tool may access dynamic external data. Such a contradiction can mislead the agent about the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose, followed by parameter details and constraints. Every sentence adds value, and the formatting with code examples improves clarity without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only lookup with an output schema present, the description covers input formats, case-insensitivity, scope limitations, and error behavior. The only flaw is the annotation contradiction, but the description itself is fully self-contained for invocation purposes.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With schema description coverage at 0%, the description carries the full burden for parameter meaning and excels. It specifies zip_code as a 5-digit US ZIP and variable as either an ACS variable code or a friendly store-column name, both case-insensitive. This adds rich detail beyond the bare property titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Raw value of a single ACS variable for a ZIP' — a specific verb+resource pair that clearly states what the tool does. The 'escape hatch' framing explicitly distinguishes it from the named sibling tools like get_income and get_demographics, which target specific variable sets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The 'escape hatch' label provides explicit guidance: use this tool when the other, more targeted siblings don't cover a desired variable. It also notes that unknown variables error with the full list, which helps the agent understand failure mode and fallback behavior.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.)
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| name | No | Census name for the area |
| zcta | Yes | 5-digit ZIP Code Tabulation Area |
| vintage | Yes | ACS 5-year data vintage (end year) |
| median_age | No | Median age of the population, in years |
| population | No | Total population (ACS 5-year estimate) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=true, and the description adds that the data are ACS 5-year estimates and that age-bracket breakdowns are on the roadmap. This provides useful context beyond the annotations without contradicting them.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences (or three lines) long, front-loaded with the core purpose, and includes only essential details like the parameter format and the roadmap limitation. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with one parameter and an output schema, the description covers the purpose, the parameter format, the data source, and what is not yet included. It is sufficiently complete without needing to explain return values in detail.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for zip_code (0% coverage), but the description includes '`zip_code`: a 5-digit US ZIP,' which supplies the format and meaning. This compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool returns population and median age for a ZIP, using the verb 'Returns' in the second sentence. It distinguishes itself from sibling tools like get_income or get_housing by naming the specific metrics it provides.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: use when you need population and median age for a ZIP. There is no explicit mention of when not to use it or which alternative to pick for other demographics, though the roadmap note hints that age-bracket breakdowns are not yet available.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| name | No | Census name for the area |
| zcta | Yes | 5-digit ZIP Code Tabulation Area |
| vintage | Yes | ACS 5-year data vintage (end year) |
| bachelors_plus_pct | No | Percent of those 25+ with a bachelor's degree or higher (0-100) |
| population_25_plus | No | Population aged 25 and over (the attainment base) |
| graduate_or_professional_pct | No | Percent of those 25+ with a graduate or professional degree (master's, professional, or doctorate) (0-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds meaningful behavioral context beyond the annotations: it specifies the population base (aged 25 and over), the exact metrics (bachelor's+ and graduate degree percentages), and the data source (ACS 5-year estimates). This is valuable context beyond the readOnlyHint and openWorldHint annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise and front-loaded. The first sentence gives the primary purpose in a compact format ('Educational attainment for a ZIP: % bachelor's+ and % graduate degree.'), and the second sentence adds essential details. No unnecessary words or repetition.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter, an output schema, and clear annotations, the description is complete. It covers the purpose, the parameter format, the population denominator, the metrics, and the data source. There is no missing critical information that would prevent an agent from using the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly explains the zip_code parameter: '`zip_code`: a 5-digit US ZIP.' This adds format validation (5-digit) and clarifies its role, which is crucial since the input schema only defines it as a string with no description. The schema coverage is 0%, so this compensation is welcome.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states what the tool does: 'Educational attainment for a ZIP: % bachelor's+ and % graduate degree.' It specifies the resource (ZIP) and the data returned (education percentages), making the purpose clear. However, it does not explicitly distinguish itself from sibling tools like get_income or get_demographics, but the focus on education is specific enough to separate it.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by context: it says 'Of the population aged 25 and over, returns the percent...' which suggests it is to be used when education data for a ZIP is needed. However, it does not explicitly state when to use this tool over alternatives or mention any exclusions, so the guidance is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| name | No | Census name for the area |
| zcta | Yes | 5-digit ZIP Code Tabulation Area |
| vintage | Yes | ACS 5-year data vintage (end year) |
| occupied_units | No | Total occupied housing units |
| median_gross_rent | No | Median gross rent (rent + utilities), monthly |
| median_home_value | No | Median value of owner-occupied homes |
| owner_occupied_pct | No | Percent of occupied units that are owner-occupied (0-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description discloses important behavioral details: it returns ACS 5-year estimates and calls out the top-coding caveat for median home value at $2,000,001, explaining that values like Atherton's 94027 represent '$2M or more' rather than exact figures. This adds significant interpretive context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and well-structured, around 100 words across three sentences plus a note. Every sentence contributes: the first introduces the metrics, the second defines the input and return fields, and the third adds a crucial caveat. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description need not restate return formats. It covers the essential context: data source (ACS 5-year), the specific variables, and a critical interpretation warning. This is complete for a single-ZIP housing data tool with strong annotations and an output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema only labels zip_code as 'Zip Code' with type string (0% schema description coverage). The description compensates fully by stating that zip_code is a 5-digit US ZIP and providing an example (Atherton 94027) within a realistic context, giving the agent precise format and usage guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly identifies the tool as providing housing measures for a ZIP, specifically home value, rent, and owner-occupied share. This distinguishes it from sibling tools like get_income or get_demographics by naming the exact metrics returned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description conveys a clear context for use — 'Housing measures for a ZIP' — and enumerates the variables, making it obvious when this tool is appropriate. It does not explicitly exclude alternatives or name sibling tools, but the context is strong enough to guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| name | No | Census name for the area |
| zcta | Yes | 5-digit ZIP Code Tabulation Area |
| vintage | Yes | ACS 5-year data vintage (end year) |
| total_households | No | Total number of households |
| per_capita_income | No | Per-capita income |
| median_household_income | No | Median household income |
| households_200k_plus_pct | No | Percent of households with income $200k+ (0-100) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses the ACS top-coding limit ($250,001) and explains how to interpret the result for wealthy ZIPs, which is critical behavioral context beyond the readOnlyHint and openWorldHint annotations. It also specifies data source and units, adding meaningful transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with the core purpose, followed by a concise parameter explanation and a crucial caveat. Every sentence adds value, with no redundancy or padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (single parameter, no enums), and the description covers the data source, the top-coding nuance, and the parameter format. The presence of an output schema handles return values, so the description is complete for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides no description for zip_code, but the description fully compensates by explicitly defining it as a 5-digit US ZIP and connecting it to the returned metrics. This is a clear, complete explanation of the parameter's meaning.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool provides ZIP-level income measures, enumerating median household income, per-capita income, and % $200k+. It differentiates itself from siblings by focusing specifically on income, not demographics or housing.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for income data but does not explicitly compare with alternatives like get_demographics or compare_zips. It lacks clear 'when to use' or 'when not to use' statements, leaving guidance implied rather than directly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| zip_code | Yes |
| Name | Required | Description |
|---|---|---|
| name | No | Census name for the area, e.g. 'ZCTA5 90069' |
| zcta | Yes | 5-digit ZIP Code Tabulation Area |
| vintage | Yes | ACS 5-year data vintage (end year) |
| population | No | Total population (ACS 5-year estimate) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint and openWorldHint annotations, the description adds valuable behavioral context: the ~2% error rate for ZIPs without ZCTAs and the return of the ACS data vintage. This helps the agent anticipate edge cases.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is compact and front-loaded with the core purpose. It includes a param note and caveat without excessive detail, though the structure is slightly dense with multiple ideas in a few sentences.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read-only tool with an output schema available, the description covers purpose, parameter, usage context, and error behavior. Nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides no description for zip_code (0% coverage), but the tool description fully explains it as a 5-digit US ZIP and its role in validation. This completely compensates for the schema gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool confirms a ZIP maps to a Census ZCTA and returns its name and population, using a specific verb and resource. This distinguishes it from sibling tools like get_income or find_zips.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear usage context by calling it 'a good first call to validate a ZIP before asking for more detail.' However, it doesn't explicitly name alternatives or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.2compare_zipsfind_zipsget_acs_variableget_demographicsget_educationget_housingget_incomelookup_zipEach 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
US ZIP code intelligence: demographics, weather, tax, crime, housing, voting, and more.
Query US Census Bureau data: demographics, economics, and housing statistics.
Population, income, poverty, education, housing, and commuting from the US Census ACS
Zippopotam MCP — wraps Zippopotam.us ZIP/postal code API (free, no auth)
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mcpwright/census-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
