README.md
Census API MCP Server
Access U.S. Census Bureau data including demographics, population, income, housing, and more.
Data Available
- American Community Survey (ACS) - Detailed demographic and socioeconomic data
- 1-year estimates (
acs/acs1) - Areas with 65,000+ population - 5-year estimates (
acs/acs5) - All areas, more reliable for small populations
- 1-year estimates (
- Decennial Census (
dec/pl) - Official population counts every 10 years - Economic Census - Business and industry statistics
- Population Estimates - Annual population estimates between censuses
Setup
- Get a free API key at: https://api.census.gov/data/key_signup.html
- Add to your MCP config:
{
"census": {
"command": "node",
"args": ["/path/to/census-api/dist/index.js"],
"env": {
"CENSUS_API_KEY": "your-api-key"
}
}
}
Tools
`query`
Fetch Census data with full control over variables and geography.
| Parameter | Required | Description |
|---|---|---|
| year | Yes | Data year (e.g., "2022") |
| dataset | Yes | Dataset path (e.g., "acs/acs1", "acs/acs5", "dec/pl") |
| variables | Yes | Comma-separated variable codes (e.g., "NAME,B19013_001E") |
| forClause | Yes | Geography to fetch (e.g., "state:", "county:", "state:06") |
| inClause | No | Parent geography for nested queries (e.g., "state:06" when getting counties) |
Example: Get median household income for all states
year: "2022"
dataset: "acs/acs5"
variables: "NAME,B19013_001E"
forClause: "state:*"
`list_datasets`
List available Census datasets for a given year.
| Parameter | Required | Description |
|---|---|---|
| year | Yes | Year to list datasets for |
`list_variables`
Search for variables in a dataset. Useful for finding the right variable codes.
| Parameter | Required | Description |
|---|---|---|
| year | Yes | Data year |
| dataset | Yes | Dataset path |
| search | No | Keyword to filter (e.g., "income", "population") |
| limit | No | Max results (default 50) |
Example: Find income-related variables
year: "2022"
dataset: "acs/acs5"
search: "income"
`list_geographies`
List available geographic levels for a dataset.
| Parameter | Required | Description |
|---|---|---|
| year | Yes | Data year |
| dataset | Yes | Dataset path |
`get_fips`
Get FIPS codes for states, counties, or other geographies.
| Parameter | Required | Description |
|---|---|---|
| year | Yes | Data year |
| dataset | Yes | Dataset path |
| geography | Yes | Level (e.g., "state", "county") |
| inClause | No | Parent geography filter |
Example: Get all county FIPS codes in California
year: "2022"
dataset: "acs/acs5"
geography: "county"
inClause: "state:06"
Common Variables
| Variable | Description |
|---|---|
| B01003_001E | Total Population |
| B19013_001E | Median Household Income |
| B25077_001E | Median Home Value |
| B23025_005E | Unemployed Population |
| B15003_022E | Bachelor's Degree holders |
| B25064_001E | Median Gross Rent |
Rate Limits
- No strict rate limit with API key
- Without key: 500 requests/day
Documentation
- API Documentation: https://www.census.gov/data/developers/guidance.html
- Variable Search: https://api.census.gov/data.html
Tools 5
queryFetch Census data with full control over variables and geography.list_datasetsList available Census datasets for a given year.list_variablesSearch for variables in a dataset.list_geographiesList available geographic levels for a dataset.get_fipsGet FIPS codes for states, counties, or other geographies.Environment Variables
CENSUS_API_KEYrequiredAPI key obtained from the U.S. Census Bureau website.Try it
→What is the total population of California based on the 2022 ACS 5-year estimates?
→Find the median household income variable code for the 2022 ACS dataset.
→List all available geographic levels for the 2022 Decennial Census.
→Get the FIPS codes for all counties in California using the 2022 ACS data.