# 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
- **Decennial Census** (`dec/pl`) - Official population counts every 10 years
- **Economic Census** - Business and industry statistics
- **Population Estimates** - Annual population estimates between censuses
## Setup
1. Get a free API key at: https://api.census.gov/data/key_signup.html
2. Add to your MCP config:
```json
{
"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
