io.github.cyanheads/census-mcp-server

Official8 toolsLive

by cyanheads · TypeScript

Query U.S. Census Bureau data, variables, and geography via MCP.

Query U.S. Census Bureau data, variables, and geography via Model Context Protocol (MCP). The server supports two transport modes: STDIO and Streamable HTTP. It provides access to census datasets, related variables, and geographic identifiers useful for downstream applications that need demographic or open government data.

🛠️ Key Features

MCP server for U.S. Census Bureau querying
Access to data, variables, and geography
Transport: STDIO or Streamable HTTP
Topics include: acs, census, census-bureau, fips, geography, government-data, open-data

🚀 Use Cases

Retrieving demographic data and related variable definitions
Working with geography and FIPS-based identifiers
Integrating census lookups into LLM workflows via MCP

⚡ Developer Benefits

Fits Model Context Protocol tooling via mcp / model-context-protocol
Supports streaming access over Streamable HTTP and local integration via stdio
Repository aligns with developer ecosystems (also referenced: bun, llm)

⚠️ Limitations

Coverage described is specifically U.S. Census Bureau data, variables, and geography
The excerpt indicates “8 Tools,” but tool names and capabilities are not provided here

Topics

acsaibuncensuscensus-bureaudemographic-datafipsgeographygovernment-datallmmcpmcp-servermodel-context-protocolopen-datastdiostreamable-http

Captured live from the server via tools/list.

census_list_datasets

Browse available Census Bureau datasets with their supported vintage years. Use as the starting point when the right dataset is unknown — ACS5, ACS1, and their profile, subject, and comparison tables, population estimates, the decennial census files, and the business datasets (County Business Patterns, Economic Census, Nonemployer Statistics) serve different use cases. Pass the dataset_id value to the dataset parameter in other census tools. Each description names the predicates a dataset requires and the geography levels it publishes, both of which vary by dataset.

Parameters1

filter

string

optional

Keyword to filter datasets by name or description. Omit to list all datasets.

Raw schema

{
  "type": "object",
  "properties": {
    "filter": {
      "description": "Keyword to filter datasets by name or description. Omit to list all datasets.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

census_list_geographies

List the geography levels available for a given Census dataset and year, along with the parent geographies each level requires. Use before querying to confirm that the target geography level exists — ACS1 omits many sub-state levels, and not all datasets support tracts or block groups. The geography_level values returned here are the valid inputs to the geography_level parameter in census_query_data and census_compare_geographies.

Parameters2

dataset	string	required	Dataset code (e.g., "acs/acs5", "acs/acs1"). Use census_list_datasets to discover 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.
year	number	optional	Vintage year. Defaults to the latest available year for the dataset.

Raw schema

{
  "type": "object",
  "properties": {
    "dataset": {
      "type": "string",
      "description": "Dataset code (e.g., \"acs/acs5\", \"acs/acs1\"). Use census_list_datasets to discover 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."
    },
    "year": {
      "description": "Vintage year. Defaults to the latest available year for the dataset.",
      "type": "number"
    }
  },
  "required": [
    "dataset"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

census_search_variables

Search Census variables by keyword across variable labels and concept groups. Returns variable codes with human-readable labels — use this to go from a concept like "median household income" to the variable code B19013_001E needed for data queries. On ACS datasets it returns both estimate (E suffix) and margin-of-error (M suffix) codes so you can request both; the ACS comparison profiles (acs/acs5/cprofile, acs/acs1/cprofile) and the other dataset families publish no margins of error. Also use it to find the predicate codes a dataset filters on, such as NAICS2017 in cbp. Adding a word narrows the results, since every word must match; when totalMatches exceeds the limit, a more specific query reaches the rest.

Parameters4

query	string	required	Keywords to search (e.g., "median household income", "poverty", "bachelor's degree"). Each word must match a whole word of the label or of the concept, ignoring case and punctuation, so "rate" does not match "separated". A column shared across tables, such as GEO_ID, is matched on its label only, and a margin of error on its estimate's label. When no variable contains every word, the results are the variables containing the most words, and the notice says how many that was.
dataset	string	optional	Dataset to search within (default: "acs/acs5"). Use census_list_datasets to discover options. 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, and the default year is that dataset's latest.
year	number	optional	Vintage year to search (default: latest available for the dataset).
limit	integer	optional	Maximum results to return (default: 20, max: 100). Increase if totalMatches greatly exceeds the limit.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Keywords to search (e.g., \"median household income\", \"poverty\", \"bachelor's degree\"). Each word must match a whole word of the label or of the concept, ignoring case and punctuation, so \"rate\" does not match \"separated\". A column shared across tables, such as GEO_ID, is matched on its label only, and a margin of error on its estimate's label. When no variable contains every word, the results are the variables containing the most words, and the notice says how many that was."
    },
    "dataset": {
      "description": "Dataset to search within (default: \"acs/acs5\"). Use census_list_datasets to discover options. 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, and the default year is that dataset's latest.",
      "type": "string"
    },
    "year": {
      "description": "Vintage year to search (default: latest available for the dataset).",
      "type": "number"
    },
    "limit": {
      "description": "Maximum results to return (default: 20, max: 100). Increase if totalMatches greatly exceeds the limit.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

census_get_variable

Fetch full metadata for one or more Census variable codes — label, concept group, predicate type, the table's universe, and margin-of-error sibling references. Use to confirm a variable code before building a query, or to look up what a known code means. On ACS datasets it returns estimate_code and moe_code sibling references so you can request both without a separate search, and a margin-of-error code carries attribute_of and attribute_type MARGIN_OF_ERROR as the Census publishes them; the ACS comparison profiles (acs/acs5/cprofile, acs/acs1/cprofile) and the other dataset families publish no margins of error and carry none of these fields. It also resolves the annotation and flag columns the data tools accept, such as B19013_001EA or EMP_F, naming the column each one belongs to, and predicate codes such as NAICS2017 or SEX, confirming a filter dimension exists in a dataset before a query uses it — for the values a dimension accepts rather than the dimension itself, call census_list_predicate_values.

Parameters3

variables	array	required	One or more variable codes to look up (e.g., ["B19013_001E", "B19013_001M"]). Codes are trimmed and matched regardless of case, and the response echoes the dataset's own spelling — uppercase everywhere except the comparison profiles' significance columns (e.g., CP03_2024to2019_062SS).
dataset	string	optional	Dataset the variables belong to (default: "acs/acs5"). Use census_list_datasets to discover 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.
year	number	optional	Vintage year (default: latest available for the dataset).

Raw schema

{
  "type": "object",
  "properties": {
    "variables": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "One or more variable codes to look up (e.g., [\"B19013_001E\", \"B19013_001M\"]). Codes are trimmed and matched regardless of case, and the response echoes the dataset's own spelling — uppercase everywhere except the comparison profiles' significance columns (e.g., CP03_2024to2019_062SS)."
    },
    "dataset": {
      "description": "Dataset the variables belong to (default: \"acs/acs5\"). Use census_list_datasets to discover 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"
    }
  },
  "required": [
    "variables"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

census_list_predicate_values

List the codes a Census filter dimension accepts, so a predicates map can be written without guessing. Answers the question left open when census_query_data or census_compare_geographies reports that a dimension was left unset. Which route a dimension takes depends on the vintage: NAICS and POPGROUP always publish a value list in the dataset dictionary, and on the current vintages EMPSZES, LFO, RCPSZES, TAXSTAT, and TYPOP publish none and are enumerated here against the live data endpoint instead. A dictionary value list is a classification shared across Census products rather than a list of what one dataset serves, and roughly half of its codes typically return no rows anywhere — those are checked against the dataset's own published rows and dropped, and the response source field says whether that check ran. The dictionary lists run to thousands of codes and are best narrowed with query. Pass the returned code as the dimension's value in predicates.

Parameters6

predicate	string	required	Filter dimension code to enumerate (e.g., "EMPSZES", "LFO", "POPGROUP", "NAICS2017"). Trimmed and uppercased, and the response echoes that spelling. The response notice of census_query_data names the dimensions a dataset declares, and census_search_variables finds them by keyword.
dataset	string	required	Dataset the dimension belongs to (e.g., "cbp", "nonemp", "ecnbasic", "dec/ddhca", "pep/charv", "acs/acs1/spp"). Use census_list_datasets to discover valid values. Case is ignored, and a two-part code can be given by its last part alone — "ddhca" is dec/ddhca, "charv" is pep/charv. Three-part codes such as acs/acs1/spp must be given in full. The response echoes the resolved code. Dimension codes are vintage-specific, so the dataset and year must match the query the values are for.
year	number	optional	Vintage year (default: latest available for the dataset).
query	string	optional	Keyword to narrow the list, matched case-insensitively against each code and label (e.g., "software" against NAICS2017, "exempt" against TAXSTAT). Omit to list from the start. NAICS and POPGROUP run to thousands of codes, so a keyword is the practical way to use them.
within_naics	any	optional	Industry code to scope the enumeration by, for dimensions the Census publishes per industry. On ecnbasic, TAXSTAT and TYPOP return only the all-establishments row until a NAICS sector is named — pass a sector code such as "62" (Health Care) or "42" (Wholesale Trade) and the result is complete for that industry alone. Ignored for dimensions with a published value list. Get sector codes by calling this tool on the dataset's own NAICS dimension. Blank is treated as omitted.
limit	integer	optional	Maximum codes to return (default: 50, max: 500). totalCount says how many matched.

Raw schema

{
  "type": "object",
  "properties": {
    "predicate": {
      "type": "string",
      "description": "Filter dimension code to enumerate (e.g., \"EMPSZES\", \"LFO\", \"POPGROUP\", \"NAICS2017\"). Trimmed and uppercased, and the response echoes that spelling. The response notice of census_query_data names the dimensions a dataset declares, and census_search_variables finds them by keyword."
    },
    "dataset": {
      "type": "string",
      "description": "Dataset the dimension belongs to (e.g., \"cbp\", \"nonemp\", \"ecnbasic\", \"dec/ddhca\", \"pep/charv\", \"acs/acs1/spp\"). Use census_list_datasets to discover valid values. Case is ignored, and a two-part code can be given by its last part alone — \"ddhca\" is dec/ddhca, \"charv\" is pep/charv. Three-part codes such as acs/acs1/spp must be given in full. The response echoes the resolved code. Dimension codes are vintage-specific, so the dataset and year must match the query the values are for."
    },
    "year": {
      "description": "Vintage year (default: latest available for the dataset).",
      "type": "number"
    },
    "query": {
      "description": "Keyword to narrow the list, matched case-insensitively against each code and label (e.g., \"software\" against NAICS2017, \"exempt\" against TAXSTAT). Omit to list from the start. NAICS and POPGROUP run to thousands of codes, so a keyword is the practical way to use them.",
      "type": "string"
    },
    "within_naics": {
      "description": "Industry code to scope the enumeration by, for dimensions the Census publishes per industry. On ecnbasic, TAXSTAT and TYPOP return only the all-establishments row until a NAICS sector is named — pass a sector code such as \"62\" (Health Care) or \"42\" (Wholesale Trade) and the result is complete for that industry alone. Ignored for dimensions with a published value list. Get sector codes by calling this tool on the dataset's own NAICS dimension. Blank is treated as omitted.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{2,8}(-\\d{2})?$",
          "description": "A NAICS code: 2 to 8 digits, or a hyphenated sector range such as \"31-33\"."
        }
      ]
    },
    "limit": {
      "description": "Maximum codes to return (default: 50, max: 500). totalCount says how many matched.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "predicate",
    "dataset"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

census_resolve_geography

Resolve a place name, ZIP code, or street address to Census FIPS identifiers. Converts names like "King County, WA", "Seattle, WA", or "Seattle-Tacoma-Bellevue, WA", and ZIPs like "98109", to the codes required by census_query_data and census_compare_geographies. Use before querying when you have a place name rather than raw FIPS codes — state_fips maps to parent_fips and fips_summary maps to geography_fips in downstream tools, and geography_type is itself the geography_level to query at.

Parameters3

name	string	required	Place name (e.g., "King County, WA", "Seattle, WA", "California"), 5-digit ZIP code (e.g., "98109", resolved to its ZIP Code Tabulation Area), or street address (e.g., "1600 Pennsylvania Ave NW, Washington, DC 20500"). Include the state after a comma — its abbreviation or full name, as in "Chatham County, Georgia" — to disambiguate places with common names. It narrows a statistical area as well, matching any state the area spans, so "Kansas City, MO" and "Kansas City, KS" both reach the MO-KS metro area. Matching ignores case, reads "Saint" and "St." as the same word, and accepts unaccented spellings ("Dona Ana County, NM"). For a statistical area a leading city is enough ("Denver, CO" for the Denver-Aurora-Centennial metro area), and an older full name resolves through its leading city ("Denver-Aurora-Lakewood, CO").
geography_type	string	optional	Geography level to resolve to, named exactly as census_query_data's geography_level and census_list_geographies name it. Auto-detection covers only state, county, place, tract, and zip code tabulation area: zip code tabulation area for a 5-digit ZIP or ZIP+4 — the ACS's ZIP-shaped area, not cbp's "zip code" level, which takes the ZIP itself with no resolution — state for a two-letter abbreviation or a spelled-out state name, county when the name contains the word "County" or "Parish", county then place for the word "Borough" (an Alaska borough is a county, a PA or NJ borough a place), tract for the word "Tract", otherwise place (incorporated places and census-designated places together) with a fallback to county, where a census-designated place answers only when no incorporated place or county has the exact name — "Arlington, VA" is Arlington County, and set "place" to reach the Arlington CDP. The other four are never auto-detected and must be set explicitly, because their names overlap city names — "metropolitan statistical area/micropolitan statistical area" covers both metro and micro areas and yields a 5-digit code, "combined statistical area" yields a 3-digit code, "consolidated city" covers the eight merged city-county governments (Nashville-Davidson, Louisville/Jefferson County, Indianapolis, Athens-Clarke County, Augusta-Richmond County, Butte-Silver Bow, Milford CT, Greeley County KS), and "economic place" yields the 8-digit code ecnbasic 2022 publishes a place under: the 3-digit county it lies in (000 when it spans counties) followed by its 5-digit place code. Economic places are the incorporated places, census-designated places, and county subdivisions the 2022 Economic Census tabulates, plus each county's remainder ("Balance of Adams County, WA"). Setting it explicitly also overrides auto-detection — "New York" auto-detects as the state, so New York City needs "place".
county_fips	string	optional	County FIPS code to resolve within — 1 to 3 digits, zero-padded here to the 3 the Census stores. A tract name is unique only inside its county, so a bare tract name matching two counties comes back as ambiguous_name until this is set: take the countyFips of the candidate you want from that error and re-call. Only county and tract sit within a county, so this restricts resolution to those two levels — pairing it with any other geography_type, or with a street address, is a county_scope_unsupported error rather than a scope quietly dropped. census_query_data takes the same code as its own county_fips but pads nothing, so hand it the 3-digit county_fips returned here, not the shorter value.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Place name (e.g., \"King County, WA\", \"Seattle, WA\", \"California\"), 5-digit ZIP code (e.g., \"98109\", resolved to its ZIP Code Tabulation Area), or street address (e.g., \"1600 Pennsylvania Ave NW, Washington, DC 20500\"). Include the state after a comma — its abbreviation or full name, as in \"Chatham County, Georgia\" — to disambiguate places with common names. It narrows a statistical area as well, matching any state the area spans, so \"Kansas City, MO\" and \"Kansas City, KS\" both reach the MO-KS metro area. Matching ignores case, reads \"Saint\" and \"St.\" as the same word, and accepts unaccented spellings (\"Dona Ana County, NM\"). For a statistical area a leading city is enough (\"Denver, CO\" for the Denver-Aurora-Centennial metro area), and an older full name resolves through its leading city (\"Denver-Aurora-Lakewood, CO\")."
    },
    "geography_type": {
      "description": "Geography level to resolve to, named exactly as census_query_data's geography_level and census_list_geographies name it. Auto-detection covers only state, county, place, tract, and zip code tabulation area: zip code tabulation area for a 5-digit ZIP or ZIP+4 — the ACS's ZIP-shaped area, not cbp's \"zip code\" level, which takes the ZIP itself with no resolution — state for a two-letter abbreviation or a spelled-out state name, county when the name contains the word \"County\" or \"Parish\", county then place for the word \"Borough\" (an Alaska borough is a county, a PA or NJ borough a place), tract for the word \"Tract\", otherwise place (incorporated places and census-designated places together) with a fallback to county, where a census-designated place answers only when no incorporated place or county has the exact name — \"Arlington, VA\" is Arlington County, and set \"place\" to reach the Arlington CDP. The other four are never auto-detected and must be set explicitly, because their names overlap city names — \"metropolitan statistical area/micropolitan statistical area\" covers both metro and micro areas and yields a 5-digit code, \"combined statistical area\" yields a 3-digit code, \"consolidated city\" covers the eight merged city-county governments (Nashville-Davidson, Louisville/Jefferson County, Indianapolis, Athens-Clarke County, Augusta-Richmond County, Butte-Silver Bow, Milford CT, Greeley County KS), and \"economic place\" yields the 8-digit code ecnbasic 2022 publishes a place under: the 3-digit county it lies in (000 when it spans counties) followed by its 5-digit place code. Economic places are the incorporated places, census-designated places, and county subdivisions the 2022 Economic Census tabulates, plus each county's remainder (\"Balance of Adams County, WA\"). Setting it explicitly also overrides auto-detection — \"New York\" auto-detects as the state, so New York City needs \"place\".",
      "type": "string",
      "enum": [
        "state",
        "county",
        "place",
        "tract",
        "metropolitan statistical area/micropolitan statistical area",
        "combined statistical area",
        "consolidated city",
        "zip code tabulation area",
        "economic place"
      ]
    },
    "county_fips": {
      "description": "County FIPS code to resolve within — 1 to 3 digits, zero-padded here to the 3 the Census stores. A tract name is unique only inside its county, so a bare tract name matching two counties comes back as ambiguous_name until this is set: take the countyFips of the candidate you want from that error and re-call. Only county and tract sit within a county, so this restricts resolution to those two levels — pairing it with any other geography_type, or with a street address, is a county_scope_unsupported error rather than a scope quietly dropped. census_query_data takes the same code as its own county_fips but pads nothing, so hand it the 3-digit county_fips returned here, not the shorter value.",
      "type": "string",
      "pattern": "^\\d{1,3}$"
    }
  },
  "required": [
    "name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

census_query_data

Query a Census dataset for one or more variables at a specific geography. Accepts FIPS codes for the target geography — use census_resolve_geography to convert place names to FIPS when needed. On ACS datasets, labeled estimates and margin-of-error values are returned together (the comparison profiles publish no margins), and the negative sentinel values the Census writes for an estimate or margin of error it cannot publish are decoded into the meanings the Census gives them rather than passed through as raw numbers. A value cbp, ecnbasic, or nonemp withheld is stored as 0 beside a flag, and is reported as withheld, with the meaning of its flag, rather than as a zero. Pass geography_fips as "*" for every geography at the level within the parent: rows come back in GEOID order, up to limit per call (default 50, max 500), with totalCount giving how many matched and offset reaching the rest — the order is not a ranking, so use census_compare_geographies to rank. On the business datasets (cbp, ecnbasic, nonemp), pep/charv, dec/ddhca, and acs/acs1/spp, use predicates to filter by industry, size class, or population group — a query that omits one is answered with 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. One geography can also come back on more than one row: pep/charv publishes an April estimates base alongside its July estimate, and each row carries a record field saying which it is.

Parameters11

variables	array	required	Variable codes to retrieve (e.g., ["B19013_001E", "B19013_001M"]). Codes are uppercased before the request, so "b19013_001e" reads as B19013_001E and the response is keyed by the uppercase code. 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, acs/acs1/spp), the maximum is lower, and too_many_variables states the exact number for the query. Use census_search_variables to find codes. On ACS datasets only, apart from the comparison profiles (acs/acs5/cprofile, acs/acs1/cprofile), which publish none, each estimate has a margin-of-error counterpart at the same code with the E suffix swapped for M — request both to get the margin alongside the estimate. Other dataset families (pep, dec, cbp, ecnbasic, nonemp) publish no margins of error, and an E-final code there is an ordinary code with no M sibling. A code can also name a text column rather than a measure — GEO_ID, on every dataset, is the nationally unique geography identifier and comes back under value with estimate null, which is the code to request when a stable join key is what is wanted.
geography_level	string	required	Level of the target geography (e.g., "county", "tract", "state", "zip code tabulation area"). Use census_list_geographies to see valid values for the dataset.
geography_fips	string	required	FIPS code for the target geography (e.g., "033" for a county, "*" for every geography at the level within the parent, returned up to limit rows per call and paged with offset). Use census_resolve_geography to obtain this value — it is returned as fips_summary. The Census API matches this literally and its width follows geography_level, so it is passed through unpadded: a county is 3 digits ("051", not "51") and a tract is 6. parent_fips and county_fips are zero-padded for you; this one is not.
parent_fips	any	optional	State FIPS code when querying sub-state levels (e.g., "53" for Washington). Required for county, tract, and block-group queries. census_resolve_geography returns this as state_fips. Pass "*" to span every state. Blank is treated as omitted.
county_fips	any	optional	County FIPS code when querying tracts or block groups within a specific county (e.g., "033" for King County within WA). Required for tract and block-group queries scoped to a county — use alongside parent_fips (state). census_resolve_geography returns this as county_fips. Pass "*" to span every county in the state, which is the only way a block-group query reaches a whole state. Blank is treated as omitted.
tract_fips	any	optional	Census tract code scoping the query to one tract (e.g., "007101" for Census Tract 71.01), for the levels that sit within a tract — block group on acs/acs5, block group and block on dec/pl. census_resolve_geography returns it as tract_fips, and for a street address also returns the block_group_fips to pass as geography_fips. A tract code is unique only within its county, so it needs parent_fips and a concrete county_fips (not "*"). It is exactly 6 digits and is not padded, since "7101" and "71" do not name one tract. A level that does not sit within a tract rejects it. Blank is treated as omitted.
predicates	object	optional	Filter values keyed by variable code, sent as extra query parameters — e.g. {"NAICS2017": "5112"} to count only software publishers in cbp. The business datasets (cbp, ecnbasic, nonemp), pep/charv, dec/ddhca, 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 POPGROUP and a single sector on ecnbasic NAICS2022 — so an unfiltered value can read like a total without being one. 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 one row per category of that dimension for each geography, each row labelled with its category in record (e.g. {"NAICS2017": ""} gives King County one row per industry) — a breakdown that can run to over a thousand rows. 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).
dataset	string	optional	Dataset to query (default: "acs/acs5"). Use census_list_datasets to discover 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.
year	number	optional	Vintage year (default: latest available for the dataset).
limit	integer	optional	Most rows to return (default: 50, max: 500). Rows come in GEOID order, a geography's records or categories in code order, and each one counts, so a geography returned as several records (pep/charv April and July) or as one row per category of a "*" predicate takes one row each. totalCount says how many rows matched.
offset	integer	optional	Rows to skip before returning up to limit (default: 0). Pages run in GEOID order, so offset 50 with limit 50 returns rows 51–100, and the notice names the offset of the next page. An offset at or past totalCount returns no rows.

Raw schema

{
  "type": "object",
  "properties": {
    "variables": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Variable codes to retrieve (e.g., [\"B19013_001E\", \"B19013_001M\"]). Codes are uppercased before the request, so \"b19013_001e\" reads as B19013_001E and the response is keyed by the uppercase code. 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, acs/acs1/spp), the maximum is lower, and too_many_variables states the exact number for the query. Use census_search_variables to find codes. On ACS datasets only, apart from the comparison profiles (acs/acs5/cprofile, acs/acs1/cprofile), which publish none, each estimate has a margin-of-error counterpart at the same code with the E suffix swapped for M — request both to get the margin alongside the estimate. Other dataset families (pep, dec, cbp, ecnbasic, nonemp) publish no margins of error, and an E-final code there is an ordinary code with no M sibling. A code can also name a text column rather than a measure — GEO_ID, on every dataset, is the nationally unique geography identifier and comes back under value with estimate null, which is the code to request when a stable join key is what is wanted."
    },
    "geography_level": {
      "type": "string",
      "description": "Level of the target geography (e.g., \"county\", \"tract\", \"state\", \"zip code tabulation area\"). Use census_list_geographies to see valid values for the dataset."
    },
    "geography_fips": {
      "type": "string",
      "description": "FIPS code for the target geography (e.g., \"033\" for a county, \"*\" for every geography at the level within the parent, returned up to limit rows per call and paged with offset). Use census_resolve_geography to obtain this value — it is returned as fips_summary. The Census API matches this literally and its width follows geography_level, so it is passed through unpadded: a county is 3 digits (\"051\", not \"51\") and a tract is 6. parent_fips and county_fips are zero-padded for you; this one is not."
    },
    "parent_fips": {
      "description": "State FIPS code when querying sub-state levels (e.g., \"53\" for Washington). Required for county, tract, and block-group queries. census_resolve_geography returns this as state_fips. Pass \"*\" to span every 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 \"*\"."
        }
      ]
    },
    "county_fips": {
      "description": "County FIPS code when querying tracts or block groups within a specific county (e.g., \"033\" for King County within WA). Required for tract and block-group queries scoped to a county — use alongside parent_fips (state). census_resolve_geography returns this as county_fips. Pass \"*\" to span every county in the state, which is the only way a block-group query reaches a whole state. 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 \"*\"."
        }
      ]
    },
    "tract_fips": {
      "description": "Census tract code scoping the query to one tract (e.g., \"007101\" for Census Tract 71.01), for the levels that sit within a tract — block group on acs/acs5, block group and block on dec/pl. census_resolve_geography returns it as tract_fips, and for a street address also returns the block_group_fips to pass as geography_fips. A tract code is unique only within its county, so it needs parent_fips and a concrete county_fips (not \"*\"). It is exactly 6 digits and is not padded, since \"7101\" and \"71\" do not name one tract. A level that does not sit within a tract rejects it. Blank is treated as omitted.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^\\d{6}$",
          "description": "Exactly 6 digits — never padded here, and never \"*\"."
        }
      ]
    },
    "predicates": {
      "description": "Filter values keyed by variable code, sent as extra query parameters — e.g. {\"NAICS2017\": \"5112\"} to count only software publishers in cbp. The business datasets (cbp, ecnbasic, nonemp), pep/charv, dec/ddhca, 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 POPGROUP and a single sector on ecnbasic NAICS2022 — so an unfiltered value can read like a total without being one. 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 one row per category of that dimension for each geography, each row labelled with its category in record (e.g. {\"NAICS2017\": \"*\"} gives King County one row per industry) — a breakdown that can run to over a thousand rows. 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 to discover 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"
    },
    "limit": {
      "description": "Most rows to return (default: 50, max: 500). Rows come in GEOID order, a geography's records or categories in code order, and each one counts, so a geography returned as several records (pep/charv April and July) or as one row per category of a \"*\" predicate takes one row each. totalCount says how many rows matched.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "offset": {
      "description": "Rows to skip before returning up to limit (default: 0). Pages run in GEOID order, so offset 50 with limit 50 returns rows 51–100, and the notice names the offset of the next page. An offset at or past totalCount returns no rows.",
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    }
  },
  "required": [
    "variables",
    "geography_level",
    "geography_fips"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

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, 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. 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.

Parameters11

variables	array	required	Variable codes to compare (e.g., ["B19013_001E", "B19013_001M"]); the ranking is on one of them, set by sort_by. Codes are uppercased before the request, and each row is keyed by the uppercase code. 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, 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) publish no margins of error.
geography_level	string	required	The level to compare across (e.g., "state", "county", "tract"). Use census_list_geographies to see valid values for the dataset.
within	any	optional	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. Blank is treated as omitted.
within_county	any	optional	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. Blank is treated as omitted.
geographies	array	optional	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.
predicates	object	optional	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, 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 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).
dataset	string	optional	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.
year	number	optional	Vintage year (default: latest available for the dataset).
sort_by	string	optional	Variable code to rank on (default: the first code in variables), uppercased 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.
sort_dir	string	optional	Sort direction (default: "desc" — highest value first).
limit	integer	optional	Maximum geographies to return (default: 50, max: 500). When results are truncated, totalCount says how many matched.

Raw 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 uppercased before the request, and each row is keyed by the uppercase code. 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, 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) 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. 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. 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, 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 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), uppercased 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 to return (default: 50, max: 500). When results are truncated, totalCount says how many matched.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    }
  },
  "required": [
    "variables",
    "geography_level"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md24 KBView on GitHub

@cyanheads/census-mcp-server

Query U.S. Census Bureau data, variables, and geography via MCP. STDIO or Streamable HTTP.

8 Tools

MCP SDK TypeScript

Public Hosted Server: https://census.caseyjhand.com/mcp

Overview

U.S. Census Bureau data — datasets, variables, and geography — via the Census Data API, TIGERweb, and the Census Geocoder. Discover datasets and variables, resolve place names or addresses to FIPS codes, and query or rank demographic, economic, and housing estimates across geographies from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`census_list_datasets`	Browse available Census Bureau datasets (ACS5 and ACS1 with their profile, subject, and comparison tables, ACS Supplemental Estimates and Selected Population Profiles, Population Estimates, Decennial, County Business Patterns, Economic Census, Nonemployer Statistics) with vintage years and dataset codes.
`census_list_geographies`	List the geography levels supported by a dataset and year, with parent requirements and example FIPS values.
`census_search_variables`	Keyword search across variable labels and concept groups. On ACS, returns estimate and margin-of-error codes together.
`census_get_variable`	Fetch full metadata for one or more variable codes — label, concept, predicate type, universe, MOE sibling — including the annotation and flag columns the data tools accept.
`census_list_predicate_values`	List the codes a filter dimension accepts (`EMPSZES`, `LFO`, `POPGROUP`, `NAICS2017`…), from the dataset dictionary or a live wildcard enumeration.
`census_resolve_geography`	Convert place names (e.g., "King County, WA"), ZIP codes, or street addresses to Census FIPS identifiers via TIGERweb and Census Geocoder.
`census_query_data`	Query a Census dataset for variables at a specific geography. Returns estimates with MOE, Census sentinel values and withheld business values resolved to their published meanings, and predicate filtering for the business datasets.
`census_compare_geographies`	Rank and compare variables across multiple geographies — all counties in a state, all states nationally, or a named set. Sorted table output, with the same predicate filtering.

Capability reference

`census_list_datasets` _tool

Returns dataset codes, names, descriptions, and available vintage years
Covers ACS5 with its Data Profiles, Subject Tables, and Comparison Profiles; ACS1 with its Data Profiles, Subject Tables, Comparison Profiles, and Selected Population Profiles (acs/acs1/spp); ACS 1-Year Supplemental Estimates (acs/acsse); Population Estimates; the 2020 Decennial files — Redistricting (P.L. 94-171), DHC (dec/dhc), Demographic Profile (dec/dp), Supplemental DHC (dec/sdhc), and DDHC-A (dec/ddhca); County Business Patterns (cbp); Economic Census (ecnbasic); and Nonemployer Statistics (nonemp)
Each description names the filter predicates the dataset requires and the geography levels it publishes — both vary by dataset
Accepts an optional keyword filter
Dataset codes (e.g., acs/acs5) are the values to pass to other tools. Every tool ignores their case and takes a two-part code by its last part alone (acs5 is acs/acs5, pl is dec/pl), echoing the resolved code; three-part codes such as acs/acs5/profile must be given in full, and a bare profile fails naming the codes that end in it
available_years is exhaustive, not a sample: any other year fails with year_not_available before a request goes out, naming the years that do work. It is narrower than what the Census API hosts — pep/charv reaches its 2020-2022 estimates through the YEAR filter inside the 2023 vintage, the cbp/nonemp vintages left out reject the NAME column every query here sends, and the Census API answers acs/acs1/spp 2008 and 2010 with server errors

`census_list_geographies` _tool

Returns one row per geography level — geography_level, whether a parent is required, required_parent_levels, and an example FIPS value
geography_level values are the exact inputs to geography_level in census_query_data and census_compare_geographies
year defaults to the dataset's latest available vintage
dataset_not_found when the dataset code is blank or unrecognized; year_not_available when the dataset has no geography data for the requested year

`census_search_variables` _tool

Whole-word search across label and concept: every query word must match (rate never matches "separated"), and when no variable contains them all, the variables with the most words come back with a notice saying so
Ranked by where the query appears — the label's last !! segment or the whole concept equal to it first, then the phrase in label and concept, label only, concept only — then by fewer !! segments, shorter concept, and code, so a table total leads its breakdown rows and an estimate leads its margin of error
A column shared across tables, such as GEO_ID, is matched on its label only and returned without a concept
On ACS datasets, returns estimate (E suffix) and margin-of-error (M suffix) codes together so both can be requested in one query — the ACS comparison profiles and the other families publish no margins of error, and an E-final code there is an ordinary code. A margin's label is the one the Census publishes (Margin of Error!!Median household income…), and search matches a margin on its estimate's label, so the two rank side by side
Also surfaces the predicate codes a dataset filters on, such as NAICS2017 in cbp
limit is an integer from 1 to 100 (default 20) — out-of-range values are rejected, not clamped; totalMatches says how many matched before the limit
Cache-backed: variables.json is fetched once per dataset+year with a configurable TTL (default 24h)

`census_get_variable` _tool

Accepts one or more variable codes (trimmed and matched regardless of case, then echoed in the dataset's own spelling) and returns metadata in the same order — label, concept, predicate type, and the table's universe when its groups.json entry publishes one
Resolves annotation and flag columns such as B19013_001EA and EMP_F from the Census per-variable endpoint, with attribute_of naming the column each belongs to and attribute_type its kind
A column shared across tables, such as GEO_ID, carries no concept — its published one joins every table's
On ACS datasets, returns estimate_code/moe_code sibling references, and a margin-of-error code carries its published label with attribute_of naming its estimate and attribute_type MARGIN_OF_ERROR; the comparison profiles and the other families publish no margins of error and carry none of these
Also resolves predicate/filter dimension codes (e.g., NAICS2017, SEX) to confirm a dimension exists in a dataset — census_list_predicate_values lists the values it accepts
dataset defaults to acs/acs5, year defaults to the dataset's latest available vintage
variable_not_found when a code isn't defined in the dataset and year

`census_list_predicate_values` _tool

Two routes, picked by where the answer lives: a dimension with a published value list is read from the dataset dictionary, one without is enumerated live by wildcarding it on the data endpoint. NAICS* and POPGROUP always publish one (thousands of codes — narrow them with query); on the current vintages EMPSZES, LFO, RCPSZES, TAXSTAT, and TYPOP publish none, so the live route is the only place their codes appear
A dictionary value list is a classification shared across Census products, not a record of what one dataset serves — dec/ddhca declares 5,543 POPGROUP codes and publishes 2,996, cbp declares 6,694 NAICS2017 codes and publishes 2,003. The declared list is checked against the dataset's own published rows and the dead codes are dropped; source says whether that check ran and the notice says how many were withheld
Keyword query matches code and label; results are sorted by code and a truncated list is disclosed rather than passed off as complete (limit an integer from 1 to 500, default 50; totalCount says how many matched)
ecnbasic publishes TAXSTAT and TYPOP per industry, so within_naics scopes the enumeration — and the notice says the result is complete for that industry alone
Live enumerations are cached per dataset, year, dimension, industry scope, and probe measure

`census_resolve_geography` _tool

Named places (e.g., "King County, WA") resolve via TIGERweb; street addresses resolve to tract level via Census Geocoder, with the address's block_group_fips and incorporated place_fips alongside
The place level covers incorporated places and census-designated places together ("Bethesda, MD" → Bethesda CDP, flagged census_designated_place). A CDP answers a name only when no incorporated place or county has it exactly, so "Paradise, CA" is Paradise town and "Arlington, VA" Arlington County; a CDP's full name ("Arlington CDP, VA") or geography_type: "place" reaches it
A 5-digit ZIP (or ZIP+4) resolves to its ZIP Code Tabulation Area (zip code tabulation area) — the ACS's ZIP-shaped area, not cbp's zip code level, which takes the ZIP itself with no resolution
The state after a comma can be an abbreviation in either case, a full name ("Chatham County, Georgia"), or a hyphenated list ("NE-IA", scoped by its first state)
Auto-detects geography_type for state, county, place, tract, and ZIP; metropolitan/micropolitan statistical areas, combined statistical areas, consolidated cities, and economic places are never auto-detected and need an explicit geography_type, since their names overlap city names
economic place returns the 8-digit code ecnbasic 2022 publishes a place under — its county, or 000 when it spans counties, then its place code (Seattle 03363000, Auburn, WA 00003180)
Optional county_fips scopes resolution to the county and tract levels only — required when a tract name matches more than one county; county_scope_unsupported when paired with any other level or a street address
Matching ignores case. A name no level matches is retried with Saint/St. respelled ("Saint Louis, MO") and with accents ignored ("Dona Ana County, NM"); a statistical area is also retried by its leading city, so a name from an earlier delineation ("Denver-Aurora-Lakewood, CO") still resolves
Prefers an exactly-named match over a partial one (e.g., "Kansas City, MO" does not resolve to North Kansas City), across levels too ("King, WA" is King County, not Kingston CDP)
A name matching more than one geography returns ambiguous_name, with every candidate's FIPS code and the state that separates them
Returns state_fips (→ parent_fips) and fips_summary (→ geography_fips) ready to pass to other tools; a statistical area omits state_fips since it can span several states, and a ZCTA omits it because its source layer carries no state

`census_query_data` _tool

Requires FIPS codes (use census_resolve_geography for place names); geography_fips: "*" returns every geography at the level within the parent, and each row carries both geography_fips and the nationally-unique geography_geoid
A wildcard returns up to limit rows (default 50, max 500) in GEOID order, and offset pages through the rest; totalCount and truncated say how many rows matched, and the notice names the range returned and the next offset. Every row counts, including each pep/charv record and each category of a "*" predicate
Up to 49 variable codes per call, fewer on datasets where label or record columns are added: the Census API accepts 50 columns per request and every query also sends NAME. too_many_variables states the exact maximum before any request goes out. Codes are case-insensitive, and an unknown one is variable_not_found
Level and parent are checked against the dataset's own geography metadata before querying — parent_required and parent_not_accepted name what's missing or unaccepted rather than surfacing a raw Census 400
Optional tract_fips (exactly 6 digits, with a concrete county_fips) scopes a block-group or decennial block query to one tract, so the block group around an address is one call: block group 2 in 53/033/007101
Optional predicates map filters the business/pep/dec datasets and acs/acs1/spp (e.g., {"NAICS2017": "5112"}); a dimension left unset applies a Census-chosen default — an all-categories total on some datasets, a single category on others — echoed per row in applied_filters. Keys are case-insensitive and a blank value counts as omitted; "*" returns one row per category, each labelled in record
A dataset that publishes more than one record per geography (pep/charv) returns multiple rows, each carrying a record field; pin one with predicates (e.g., {"MONTH": "7"})
ACS sentinel values resolve to the Census's published meanings, a controlled estimate's margin of error reads as 0, and a median in an open-ended interval is flagged open_ended. On cbp, ecnbasic, and nonemp, a value the Census withheld (stored as 0 beside a flag such as D) is reported as suppressed with the flag's meaning. A null estimate means the value is either suppressed, a text cell (returned under value), or genuinely empty
Requires CENSUS_API_KEY

`census_compare_geographies` _tool

Ranks all geographies at a level, or a named geographies list of GEOIDs/bare level codes, in one call; within/within_county scope to a state/county, omit for a national comparison
Ranks on one variable's value: sort_by (default the first code; it must be one of the requested codes, or the call fails with sort_by_not_requested), sort_dir (default desc), and limit (an integer from 1 to 500, default 50); totalCount reports how many geographies matched before the limit
A count ranks by size, not rate — rank a published percentage for a rate, e.g. S1701_C03_001E (percent below poverty, acs/acs5/subject) or DP04_0047PE (percent renter-occupied, acs/acs5/profile), both available down to tract
Same predicates map, variable limit, geography validation, and applied_filters default-echoing as census_query_data, applied to every geography in the ranking
A dataset that publishes more than one record per geography (pep/charv), or a "*" predicate, fails with ambiguous_rows unless predicates pins one (e.g., {"MONTH": "7"})
Suppressed values carry the same reasons as census_query_data and sort to the end in either direction, withheld business values included; a text value has no ordering, so sorting on it leaves rows tied, and the notice says the rows are not ranked
Requires CENSUS_API_KEY

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

Census-specific:

In-process variable cache with configurable TTL — variables.json fetched once per dataset+year, searched client-side
Three-API backend: Census Data API for data queries, TIGERweb for named-place resolution, Census Geocoder for address-to-tract
Automatic retry with backoff on all external API calls
FIPS formatting helpers — zero-padded state, county, and tract codes ready to pass between tools

Agent-friendly output:

Workflow-oriented tool surface — fips_summary and state_fips return values are ready to pass as geography_fips and parent_fips to the next tool
Suppression codes decoded — Census negative sentinel values (e.g., -666666666) and business-dataset withholding flags (e.g., D) surfaced as their published meanings instead of raw numbers or false zeros
Recovery hints on errors — ambiguous geography names include candidate lists; missing API key errors include registration URL

Getting started

Public Hosted Instance

A public instance is available at https://census.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:

json

{
  "mcpServers": {
    "census-mcp-server": {
      "type": "streamable-http",
      "url": "https://census.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

API key: Register a free key at api.census.gov/data/key_signup.html. Variable search and geography resolution work without a key; data queries (census_query_data, census_compare_geographies) require one.

Add the following to your MCP client configuration file:

json

{
  "mcpServers": {
    "census-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/census-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CENSUS_API_KEY": "your-census-api-key"
      }
    }
  }
}

Or with npx (no Bun required):

json

{
  "mcpServers": {
    "census-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/census-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info",
        "CENSUS_API_KEY": "your-census-api-key"
      }
    }
  }
}

Or with Docker:

json

{
  "mcpServers": {
    "census-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "MCP_TRANSPORT_TYPE=stdio",
        "-e", "CENSUS_API_KEY=your-census-api-key",
        "ghcr.io/cyanheads/census-mcp-server:latest"
      ]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CENSUS_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
A Census API key — register free at api.census.gov/data/key_signup.html. Required for census_query_data and census_compare_geographies; other tools work without it.

Installation

Clone the repository:

git clone https://github.com/cyanheads/census-mcp-server.git

Navigate into the directory:

cd census-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env and set CENSUS_API_KEY

Configuration

Variable	Description	Default
`CENSUS_API_KEY`	Required for data queries. Register free at api.census.gov/data/key_signup.html.	—
`CENSUS_DEFAULT_YEAR`	Default vintage year when no year is specified.	`2024`
`CENSUS_VARIABLE_CACHE_TTL_HOURS`	Hours to cache variables.json per dataset+year in memory.	`24`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_SESSION_MODE`	HTTP session mode: `stateful`, `stateless`, or `auto`. The server declares `stateless` in `src/index.ts`; set this only to override it.	`stateless`
`MCP_HTTP_PORT`	Port for HTTP server.	`3010`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (`debug`, `info`, `notice`, `warning`, `error`).	`info`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`

See .env.example for the full list of optional overrides.

Running the server

Local development

# One-time build
bun run rebuild

# Run the built server
bun run start:stdio
# or
bun run start:http

Run checks and tests:

bun run devcheck   # Lint, format, typecheck, security audit
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t census-mcp-server .
docker run --rm -e CENSUS_API_KEY=your-key -p 3010:3010 census-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/census-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Path	Purpose
`src/index.ts`	`createApp()` entry point — registers tools and initializes services.
`src/config/server-config.ts`	Census-specific env var parsing and validation with Zod.
`src/mcp-server/tools/definitions/`	Tool definitions (`*.tool.ts`).
`src/services/census-api/`	Census Data API client — data queries, suppression code mapping, retry logic.
`src/services/geography/`	Geography resolution — TIGERweb named-place lookup and Census Geocoder address-to-tract.
`src/services/variable-cache/`	In-process variables.json cache with TTL and keyword search.
`tests/`	Vitest tests mirroring `src/` structure.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

Handlers throw, framework catches — no try/catch in tool logic
Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
Register new tools via the barrel in src/mcp-server/tools/definitions/index.ts
Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (8)

census_list_datasetscensus_list_geographiescensus_search_variablescensus_get_variablecensus_list_predicate_valuescensus_resolve_geographycensus_query_datacensus_compare_geographies

Configuration

Environment variables

CENSUS_API_KEY

Census Bureau API key from api.census.gov/data/key_signup.html. Required for census_query_data and census_compare_geographies; variable search and geography resolution work without it.

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "census-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/census-mcp-server@0.6.0",
        "run",
        "start:stdio"
      ],
      "env": {
        "CENSUS_API_KEY": "<YOUR_CENSUS_API_KEY>",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

census_list_datasets

census_list_geographies

census_search_variables

census_get_variable

census_list_predicate_values

census_resolve_geography

census_query_data

census_compare_geographies

@cyanheads/census-mcp-server

Overview

Tools

Capability reference

census_list_datasets tool

census_list_geographies tool

census_search_variables tool

census_get_variable tool

census_list_predicate_values tool

census_resolve_geography tool

census_query_data tool

census_compare_geographies tool

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`census_list_datasets` _tool

`census_list_geographies` _tool

`census_search_variables` _tool

`census_get_variable` _tool

`census_list_predicate_values` _tool

`census_resolve_geography` _tool

`census_query_data` _tool

`census_compare_geographies` _tool