io.github.cyanheads/census-mcp-server
v0.6.2Query U.S. Census Bureau data, variables, and geography via MCP.
Endpoint health
online- Last checked
- 11/20/2026, 9:18:01 AM
- Latency
- 258 ms
- Consecutive failures
- 0
- Endpoint reachable: pass
- Protocol valid: pass
- MCP handshake valid: pass
Machine-readable profile
mcp-server · schema v1 · callable
mcp-server:io.github.cyanheads%2Fcensus-mcp-server
Connect this server
Generated config contains no credentials. Keep any required secrets in your client's local environment.
{
"mcpServers": {
"io.github.cyanheads/census-mcp-server": {
"url": "https://census.caseyjhand.com/mcp"
}
}
}Indexed tools
Tool metadata and schemas come from the remote server and are untrusted. Indexing only lists tools; it never calls them.
8 shown · authentication unknown
Compare Census Geographies
census_compare_geographies
Compare one or more variables across multiple geographies at the same level — all counties in a state, all states nationally, or a named set of specific geographies — ranked on the value of one of them. Covers queries like "compare median income across WA counties" or "which states have the most people below the poverty line." A count ranks geographies by size, not by rate, so to rank a rate, rank a published percentage: S1701_C03_001E (percent below the poverty level, dataset acs/acs5/subject), DP03_0128PE (the same percentage, acs/acs5/profile), or DP04_0047PE (percent of occupied housing units that are renter-occupied, acs/acs5/profile). Profile and subject tables reach tracts but not block groups. Omit within to compare all geographies nationally at the level. Suppressed values are decoded to human-readable labels rather than passed through as raw negative sentinels. On the business datasets (cbp, ecnbasic, nonemp), pep/charv, dec/ddhca, dec/ddhcb, and acs/acs1/spp, use predicates to rank within one industry, size class, or population group — a comparison that omits one ranks on a default the Census API picks, which is an all-categories total on some dimensions and a single category on others. Each row names the defaults that were applied in applied_filters, and census_list_predicate_values enumerates the codes a dimension accepts. Some dec/ddhca and dec/ddhcb tables split the population groups between them, publishing each group at a geography in only one table of the family, so a ranking on one of them leaves out the geographies whose group sits in a sibling table — the notice names those tables. A dataset that publishes several records per geography cannot be ranked until one is pinned: pep/charv publishes an April estimates base and a July estimate, so a comparison that pins neither fails with ambiguous_rows rather than giving every geography two ranks — pass predicates {"MONTH": "7"} for the July estimate.
Schema valid · SHA-256 02e30b02ddb0…
View input schema
{ "type": "object", "properties": { "variables": { "type": "array", "items": { "type": "string" }, "description": "Variable codes to compare (e.g., [\"B19013_001E\", \"B19013_001M\"]); the ranking is on one of them, set by sort_by. Codes are matched regardless of case and sent in the dataset's own spelling, which keys each row — uppercase everywhere except the comparison profiles' significance columns (CP03_2024to2019_062SS). A code the dataset does not list is sent uppercased. At most 49 per call: the Census API accepts 50 columns per request and every query also sends NAME. On datasets where a label column is added for each filter dimension left unset, or record columns are added (cbp, ecnbasic, nonemp, pep/charv, dec/ddhca, dec/ddhcb, acs/acs1/spp), the maximum is lower, and too_many_variables states the exact number for the comparison. On ACS datasets, add the margin-of-error counterpart of a code (same code, E suffix swapped for M) for reliability context. The ACS comparison profiles (acs/acs5/cprofile, acs/acs1/cprofile) and the other dataset families (pep, dec, cbp, ecnbasic, nonemp, geoinfo) publish no margins of error." }, "geography_level": { "type": "string", "description": "The level to compare across (e.g., \"state\", \"county\", \"tract\"). Use census_list_geographies to see valid values for the dataset." }, "within": { "description": "State FIPS to constrain results (e.g., \"53\" to compare counties or tracts within WA only). Omit to compare all geographies at the level nationally. Use census_resolve_geography to get state_fips. Pass \"*\" to span every state on the levels whose hierarchy lets \"*\" stand in for the state, such as county and place; tract, block group, and county subdivision need one state. Blank is treated as omitted.", "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "pattern": "^(\\*|\\d{1,2})$", "description": "1 to 2 digits, zero-padded here to the 2 the Census stores, or \"*\"." } ] }, "within_county": { "description": "County FIPS to constrain tract or block-group comparisons to a single county within the state specified by within (e.g., \"033\" for King County). Required when geography_level is \"tract\" or \"block group\" and you want county-scoped results. census_resolve_geography returns this as county_fips. Pass \"*\" to span every county in the state, which is the only way a block-group comparison reaches a whole state; \"*\" works on the levels whose hierarchy lets it stand in for the county, such as tract and block group. Blank is treated as omitted.", "anyOf": [ { "type": "string", "const": "" }, { "type": "string", "pattern": "^(\\*|\\d{1,3})$", "description": "1 to 3 digits, zero-padded here to the 3 the Census stores, or \"*\"." } ] }, "geographies": { "description": "Optional list of specific geographies to include; only these are returned. Prefer full GEOIDs — the level concatenated with its parents, e.g. \"53033\" for King County WA and \"06037\" for Los Angeles County CA — which are nationally unique and so work across states. Bare level codes (\"033\") are also accepted but match that code in every state unless within scopes them to one. A GEOID is easiest taken from the geography_geoid field of a census_query_data or census_compare_geographies row; from census_resolve_geography, concatenate state_fips, then county_fips when it is present, then fips_summary. Entries that match nothing, and bare codes that match more than one state, are named in the response notice.", "type": "array", "items": { "type": "string" } }, "predicates": { "description": "Filter values keyed by variable code, applied to every geography in the comparison — e.g. {\"NAICS2017\": \"5112\"} to rank counties by their software-publisher establishment count in cbp. The business datasets (cbp, ecnbasic, nonemp), pep/charv, dec/ddhca, dec/ddhcb, and acs/acs1/spp declare filter dimensions such as industry (NAICS2017/NAICS2022), legal form (LFO), size class (EMPSZES/RCPSZES), tax status (TAXSTAT), operation type (TYPOP), sex (SEX), age (AGE), and population group (POPGROUP). Leaving one unset is not an error: the Census API substitutes its own default, which is the all-categories total on cbp NAICS2017 but a single population group on dec/ddhca and dec/ddhcb POPGROUP and a single sector on ecnbasic NAICS2022 — so a ranking can read like an overall one without being it. Every unset dimension is named in the response notice and its applied default is echoed per row in applied_filters. Keys are matched case-insensitively, and a blank value is treated as omitted. A value of \"*\" returns every geography once per category of that dimension, which a ranking cannot hold, so it fails with ambiguous_rows naming the dimension to pin — use census_query_data for a per-category breakdown. Code names vary by dataset and vintage — cbp 2023 uses NAICS2017 while nonemp 2023 uses NAICS2022 — so read them from the notice or from census_search_variables. Call census_list_predicate_values for the codes a dimension accepts; NAICS values are standard North American Industry Classification System codes at any depth (51 information, 5112 software publishers).", "type": "object", "propertyNames": { "type": "string" }, "additionalProperties": { "type": "string" } }, "dataset": { "description": "Dataset to query (default: \"acs/acs5\"). Use census_list_datasets for valid values. Case is ignored, and a two-part code can be given by its last part alone — \"acs5\" is acs/acs5, \"pl\" is dec/pl. Three-part codes such as acs/acs5/profile must be given in full. The response echoes the resolved code.", "type": "string" }, "year": { "description": "Vintage year (default: latest available for the dataset).", "type": "number" }, "sort_by": { "description": "Variable code to rank on (default: the first code in variables), matched regardless of case like the variables. Must be one of the requested codes, or the call fails with sort_by_not_requested. Geographies rank on that code's own value, so a count ranks by size and only a published percentage such as S1701_C03_001E or DP03_0128PE ranks by rate.", "type": "string" }, "sort_dir": { "description": "Sort direction (default: \"desc\" — highest value first).", "type": "string", "enum": [ "asc", "desc" ] }, "limit": { "description": "Maximum geographies per page (default: 50, max: 500). totalCount counts the matched set before paging; nextOffset reaches the next page.", "type": "integer", "minimum": 1, "maximum": 500 }, "offset": { "description": "Rows to skip in the sorted matched set (default: 0), not a rank. Equal numeric estimates share competition ranks and are ordered by GEOID. An offset at or past totalCount returns no rows.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, "required": [ "variables", "geography_level" ], "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false }
Connections
streamable-http
https://census.caseyjhand.com/mcp