US Census Bureau Data Intelligence MCP Server

An Apify actor that exposes the US Census Bureau ACS (American Community Survey) API as a Model Context Protocol (MCP) server. AI assistants and developer tools can call four structured tools to retrieve state demographics, county demographics, ZIP code profiles, and side-by-side geography comparisons — all powered by the definitive source for US demographic data.

No API key is required for standard use. An optional Census API key enables higher rate limits.

---

What This Actor Does

The Census Bureau's American Community Survey is the most comprehensive ongoing statistical program in the United States, collecting information from over 3.5 million households annually. The 5-year ACS estimates provide the most detailed and statistically reliable demographic data available at the local level.

This actor parses the Census Bureau's unusual 2D-array response format (first row = column headers) into clean, normalized dicts and exposes them via MCP. The result: any AI agent can answer demographic questions about any location in the US with a single tool call.

Supported data: Population, income, age, housing, education attainment, race/ethnicity, immigration status, and employment.

---

ACS Variables Available

The following variables are available via friendly names or raw ACS codes:

Friendly Name	ACS Code	Description
total_population	B01001_001E	Total population
median_household_income	B19013_001E	Median household income (dollars)
median_age	B01002_001E	Median age (years)
housing_units	B25001_001E	Total housing units
median_home_value	B25077_001E	Median owner-occupied home value
unemployment	B23025_005E	Unemployed persons in labor force
poverty_count	B17001_002E	Persons below poverty level
bachelor_degree	B15003_022E	Persons with bachelor's degree
white_alone	B02001_002E	White alone (race)
black_alone	B02001_003E	Black or African American alone
hispanic	B03003_003E	Hispanic or Latino
foreign_born	B05002_013E	Foreign-born population
limited_english	B16004_023E	Speak English less than "very well"

Pass any subset as variables: ["total_population", "median_household_income"], or omit to get all.

---

MCP Tools Available

Point your MCP client at http://<actor-run-url>:4321 after setting serveMcp: true.

1. get_state_demographics

Retrieve ACS 5-year estimates for one or all US states.

Parameters:

Name	Type	Required	Description
state_fips	string	No	2-digit FIPS code or * for all states (default *)
year	integer	No	Survey year (default 2022)
variables	array	No	Variable names/codes. Empty = all
api_key	string	No	Census API key
limit	integer	No	Max states returned (default 60)

Returns: List of state records with state_name, state_fips, all requested variables, year, source.

Example:

{
  "name": "get_state_demographics",
  "arguments": {
    "state_fips": "*",
    "variables": ["total_population", "median_household_income", "median_age"],
    "year": 2022
  }
}

Common state FIPS codes: Alabama=01, Alaska=02, Arizona=04, Arkansas=05, California=06, Colorado=08, Connecticut=09, Delaware=10, Florida=12, Georgia=13, Hawaii=15, Idaho=16, Illinois=17, Indiana=18, Iowa=19, Kansas=20, Kentucky=21, Louisiana=22, Maine=23, Maryland=24, Massachusetts=25, Michigan=26, Minnesota=27, Mississippi=28, Missouri=29, Montana=30, Nebraska=31, Nevada=32, New Hampshire=33, New Jersey=34, New Mexico=35, New York=36, North Carolina=37, North Dakota=38, Ohio=39, Oklahoma=40, Oregon=41, Pennsylvania=42, Rhode Island=44, South Carolina=45, South Dakota=46, Tennessee=47, Texas=48, Utah=49, Vermont=50, Virginia=51, Washington=53, West Virginia=54, Wisconsin=55, Wyoming=56, DC=11

---

2. get_county_demographics

Retrieve ACS 5-year estimates for counties within a state.

Parameters:

Name	Type	Required	Description
state_fips	string	Yes	2-digit state FIPS code
county_fips	string	No	3-digit county FIPS or * for all counties (default *)
year	integer	No	Survey year (default 2022)
variables	array	No	Variable names/codes
api_key	string	No	Census API key
limit	integer	No	Max counties (default 100)

Returns: List of county records with county_name, state_fips, county_fips, all variables, year, source.

Example:

{
  "name": "get_county_demographics",
  "arguments": {
    "state_fips": "06",
    "variables": ["total_population", "median_household_income"],
    "year": 2022
  }
}

---

3. get_zip_demographics

Retrieve ACS 5-year estimates for a single ZIP Code Tabulation Area (ZCTA).

Parameters:

Name	Type	Required	Description
zip_code	string	Yes	5-digit ZIP code
year	integer	No	Survey year (default 2022)
variables	array	No	Variable names/codes
api_key	string	No	Census API key

Returns: Record with zip_code, all variables, year, source.

Note: Not all ZIPs are ZCTAs. PO Box-only ZIPs and some rural ZIPs may not have ACS coverage and will return a graceful fallback.

Example:

{
  "name": "get_zip_demographics",
  "arguments": {
    "zip_code": "10001",
    "variables": ["total_population", "median_household_income", "foreign_born"]
  }
}

---

4. compare_geographies

Compare demographic data across multiple geographies side by side. Supports states, counties, or ZIP codes.

Parameters:

Name	Type	Required	Description
geo_type	string	Yes	state, county, or zip
geo_ids	array	Yes	List of FIPS codes, STATE:COUNTY pairs, or ZIP codes
variables	array	No	Variable names/codes
year	integer	No	Survey year (default 2022)
api_key	string	No	Census API key

Returns: List of records, one per geography, with geo_id, geo_name, all variables, year, source.

Examples:

Compare three states:

{
  "name": "compare_geographies",
  "arguments": {
    "geo_type": "state",
    "geo_ids": ["06", "48", "36"],
    "variables": ["total_population", "median_household_income", "median_home_value"]
  }
}

Compare ZIP codes:

{
  "name": "compare_geographies",
  "arguments": {
    "geo_type": "zip",
    "geo_ids": ["90210", "10001", "60601"],
    "variables": ["total_population", "median_household_income"]
  }
}

Compare counties (California):

{
  "name": "compare_geographies",
  "arguments": {
    "geo_type": "county",
    "geo_ids": ["06:037", "06:073", "06:001"],
    "variables": ["total_population", "median_household_income"]
  }
}

---

Running Modes

Batch Mode (default)

Set serveMcp: false (default). The actor fetches demographic data for the specified geography and pushes results to the dataset.

State batch (default):

{
  "geoType": "state",
  "stateFips": "*",
  "year": 2022,
  "limit": 55
}

County batch:

{
  "geoType": "county",
  "stateFips": "06",
  "year": 2022
}

ZIP batch:

{
  "geoType": "zip",
  "zipCode": "90210",
  "year": 2022
}

MCP Server Mode

Set serveMcp: true. The actor starts an HTTP server on port 4321 and stays alive for up to 24 hours.

{
  "serveMcp": true,
  "year": 2022
}

---

MCP Endpoint Reference

Endpoint	Method	Description
/	GET	Health check
/health	GET	Health check
/mcp/tools	GET	List all 4 tools with schemas
/mcp/call	POST	Call a tool

---

Census API Response Format

The Census Bureau returns data as a 2D JSON array:

[
  ["NAME", "B01001_001E", "B19013_001E", "state"],
  ["California", "39538223", "84097", "06"],
  ["Texas", "29145505", "63826", "48"]
]

This actor's _parse_census_response() function automatically converts this into a list of dicts using the first row as keys, then maps raw ACS codes to friendly names. The value -666666666 (Census suppression sentinel) is converted to None.

---

Use Cases

Market Research and Site Selection

Query county or ZIP demographics to evaluate potential business locations: population density, income levels, age distribution, and housing market characteristics.

Real Estate Analysis

Combine median_home_value, median_household_income, and total_population for any geography to assess affordability and market conditions.

Public Policy and Grant Writing

Provide demographic evidence for grant applications. Query poverty counts, unemployment figures, and limited English proficiency by county or ZIP.

AI Agent Integration

Connect to Claude as an MCP server. The agent can answer: "What is the median household income in the 10 largest counties in Texas?" by calling get_county_demographics with state_fips=48 and filtering by population.

Competitive Intelligence

Compare demographics across markets your competitors operate in vs. untapped markets. Use compare_geographies for direct side-by-side output.

Academic and Journalistic Research

Journalists and researchers can query all 50 states at once for any variable, enabling data-driven stories about economic inequality, demographic shifts, or housing affordability.

Diversity and Inclusion Reporting

Pull race/ethnicity variables (white_alone, black_alone, hispanic, foreign_born) for any geography to support DEI reporting and workforce analysis.

---

Error Handling

All tools return graceful fallbacks on any error:

[{"_meta": {"error": "description", "fallback_tried": true}}]

The Census API returns HTTP 400 for invalid FIPS codes or unsupported year/variable combinations. These errors are caught and returned in the _meta structure — the actor never crashes.

---

Output Dataset Fields (State Mode)

Field	Type	Description
state_name	string	Full state name (from Census NAME field)
state_fips	string	2-digit FIPS code
total_population	integer	ACS total population estimate
median_household_income	integer	Median household income in dollars
median_age	integer	Median age in years
housing_units	integer	Total housing units
median_home_value	integer	Median owner-occupied home value
unemployment	integer	Number unemployed in labor force
poverty_count	integer	Number below poverty level
bachelor_degree	integer	Number with bachelor's degree
white_alone	integer	White alone population
black_alone	integer	Black or African American alone
hispanic	integer	Hispanic or Latino population
foreign_born	integer	Foreign-born population
limited_english	integer	Speak English less than "very well"
year	integer	ACS survey year
source	string	Always census.gov

---

Getting a Census API Key (Optional)

Free registration at: https://api.census.gov/data/key_signup.html

Without a key: 500 requests per IP per day limit. With a key: Higher limits suitable for production use.

Pass via apiKey in actor input or directly in tool arguments as api_key.

---

Technical Details

• Runtime: Python 3.11+
• Framework: Apify SDK v2+
• HTTP client: httpx (async)
• MCP server: asyncio raw TCP, HTTP/1.1
• Port: 4321
• Max server lifetime: 24 hours
• Dataset: ACS 5-year (most reliable for small geographies)
• Timeout per call: 30 seconds

---

Connecting via Claude Desktop

{
  "mcpServers": {
    "census": {
      "url": "http://<your-actor-run-url>:4321"
    }
  }
}

---

License

US Census Bureau data is US government public domain. This actor code is MIT licensed.