# US Census Bureau Intelligence MCP — ACS Demographics (`andrew_avina/census-mcp`) Actor 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-s... - **URL**: https://apify.com/andrew\_avina/census-mcp.md - **Developed by:** [Andrew Avina](https://apify.com/andrew_avina) (community) - **Categories:** MCP servers, Business - **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, NaN bookmarks - **User rating**: No ratings yet ## Pricing $3.00 / 1,000 result item returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## 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://: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:** ```json { "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:** ```json { "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:** ```json { "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: ```json { "name": "compare_geographies", "arguments": { "geo_type": "state", "geo_ids": ["06", "48", "36"], "variables": ["total_population", "median_household_income", "median_home_value"] } } ``` Compare ZIP codes: ```json { "name": "compare_geographies", "arguments": { "geo_type": "zip", "geo_ids": ["90210", "10001", "60601"], "variables": ["total_population", "median_household_income"] } } ``` Compare counties (California): ```json { "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):** ```json { "geoType": "state", "stateFips": "*", "year": 2022, "limit": 55 } ``` **County batch:** ```json { "geoType": "county", "stateFips": "06", "year": 2022 } ``` **ZIP batch:** ```json { "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. ```json { "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: ```json [ ["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: ```json [{"_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: 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 ```json { "mcpServers": { "census": { "url": "http://:4321" } } } ``` *** ### License US Census Bureau data is US government public domain. This actor code is MIT licensed. # Actor input Schema ## `serveMcp` (type: `boolean`): If true, starts the MCP HTTP server on port 4321. Leave false for one-shot batch state demographics fetch. ## `geoType` (type: `string`): Type of geography to query in batch mode: 'state', 'county', or 'zip'. ## `stateFips` (type: `string`): 2-digit state FIPS code (e.g. '06' for California). Use '*' for all states. Default '*'. ## `year` (type: `integer`): ACS 5-year survey year to query (e.g. 2022). Must have published ACS data. ## `apiKey` (type: `string`): Optional Census Bureau API key for higher rate limits. Free at https://api.census.gov/data/key\_signup.html ## `limit` (type: `integer`): Maximum number of records to return (default 60, covers all states + DC + territories). ## `zipCode` (type: `string`): 5-digit ZIP code for batch ZIP demographic lookup (only used when geoType='zip'). ## Actor input object example ```json { "serveMcp": false, "geoType": "state", "stateFips": "*", "year": 2022, "limit": 60 } ``` # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = {}; // Run the Actor and wait for it to finish const run = await client.actor("andrew_avina/census-mcp").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = {} # Run the Actor and wait for it to finish run = client.actor("andrew_avina/census-mcp").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{}' | apify call andrew_avina/census-mcp --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=andrew_avina/census-mcp", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "US Census Bureau Intelligence MCP — ACS Demographics", "description": "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-s...", "version": "0.1", "x-build-id": "FXvp3KXVajTQByBtx" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/andrew_avina~census-mcp/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-andrew_avina-census-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/andrew_avina~census-mcp/runs": { "post": { "operationId": "runs-sync-andrew_avina-census-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/andrew_avina~census-mcp/run-sync": { "post": { "operationId": "run-sync-andrew_avina-census-mcp", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "properties": { "serveMcp": { "title": "Serve MCP", "type": "boolean", "description": "If true, starts the MCP HTTP server on port 4321. Leave false for one-shot batch state demographics fetch.", "default": false }, "geoType": { "title": "Geography Type", "enum": [ "state", "county", "zip" ], "type": "string", "description": "Type of geography to query in batch mode: 'state', 'county', or 'zip'.", "default": "state" }, "stateFips": { "title": "State FIPS Code", "type": "string", "description": "2-digit state FIPS code (e.g. '06' for California). Use '*' for all states. Default '*'.", "default": "*" }, "year": { "title": "Survey Year", "minimum": 2010, "maximum": 2023, "type": "integer", "description": "ACS 5-year survey year to query (e.g. 2022). Must have published ACS data.", "default": 2022 }, "apiKey": { "title": "Census API Key", "type": "string", "description": "Optional Census Bureau API key for higher rate limits. Free at https://api.census.gov/data/key_signup.html" }, "limit": { "title": "Result Limit", "minimum": 1, "maximum": 1000, "type": "integer", "description": "Maximum number of records to return (default 60, covers all states + DC + territories).", "default": 60 }, "zipCode": { "title": "ZIP Code", "type": "string", "description": "5-digit ZIP code for batch ZIP demographic lookup (only used when geoType='zip')." } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```