# 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