# Census Housing MCP

> The U.S. Census Housing MCP Server lets your AI client pull definitive residential real estate and socioeconomic data directly from the federal government. You can calculate median home values, rent rates, ownership percentages, and vacancy counts for any specific state or county. It's built for deep market research: run full demographic profiles or custom API queries to build comprehensive local economic reports.

## Overview
- **Category:** real-estate
- **Price:** Free
- **Tags:** housing-market, residential-data, real-estate-trends, socioeconomic-profiles, census-data, property-statistics

## Description

**U.S. Census Housing Data - Real Estate & Socioeconomics**

Forget guessing games about local markets; this server gives your AI client access to definitive, raw data straight from the federal government. You're pulling official U.S. Census Bureau figures covering everything from residential property values to deep socioeconomic metrics. This isn't a summary report—it's structured data built for serious market research.

**State-Level Overviews and Metrics**

You can quickly map out the entire national picture. The `get_state_profile` tool generates an immediate, full snapshot of any state, giving you core demographic stats alongside key housing figures like population totals and income levels. For a dedicated look at just housing, `get_housing_by_state` pulls median home values, gross rent rates, owner-occupied unit counts, and vacancy percentages for every single U.S. state. You'll see exactly how the housing landscape shifts from one corner of the country to another.

**Comparing Local Market Trends Across Counties**

When you need to compare apples to apples within a single state, you use `get_housing_by_county`. This gathers essential housing data—values, rent rates, and ownership statistics—across every county inside your chosen state, letting you run direct comparisons between neighboring markets. If you want deeper context for one specific area, the `get_county_profile` tool dives into a single county's demographic makeup, giving you background stats that go way beyond just counting houses. This is how you build out a true local economic profile.

**Running Custom Census Queries**

The real power here is in `query_census`. If the built-in tools don't hit the mark, this custom API query executes virtually any dataset or variable you can think of against any geography and year supported by the Bureau. You specify exactly what you want—say, employment metrics for a specific age group in Queens during 2015—and it pulls that data point directly. It’s built to handle hyper-specific filtering rules, allowing your agent to construct reports nobody else can run.

**How This Works When Your Agent Uses It**

When you connect this server, your AI client uses these tools to build out complex economic narratives. You don't just get a number; you get the mechanism for understanding market shifts. For instance, you can use `get_state_profile` to establish baseline income and population figures, then pivot using `get_housing_by_county` to see if those median home values correlate with localized wealth pockets across multiple counties in that state. If your research requires something unique—like correlating the percentage of people over 45 with average vacancy rates—you send it through `query_census`. The result is a fully sourced, multi-layered local economic report ready for presentation.

## Tools

### get_housing_by_state
Provides housing data for every U.S. state, including owner-occupied units, renter-occupied units, and vacancies.

### get_housing_by_county
Gathers median home values and rent rates across all counties within a selected state.

### get_state_profile
Generates a comprehensive socioeconomic summary for an entire state—covering income, population, and housing data.

### get_county_profile
Retrieves key demographic data for one specific county, giving context beyond just housing numbers.

### query_census
Executes custom API queries to pull any dataset or variable (e.g., specific age groups, employment metrics) by specifying the geography and year.

## Prompt Examples

**Prompt:** 
```
What is the median home value in California?
```

**Response:** 
```
📊 **U.S. Census Bureau: Housing by State**

**California (06):**
- Median Home Value: $611,400
- Median Gross Rent: $1,768
- Owner-Occupied: 7,330,227
- Renter-Occupied: 5,903,115
```

**Prompt:** 
```
How many houses are vacant in Nevada?
```

**Response:** 
```
📊 **Housing by State**

**Nevada (32):**
- Total Housing Units: 1,310,211
- Occupied Units: 1,180,388
- Vacant Housing Units: 129,823 (9.9%)
```

**Prompt:** 
```
Use a custom query to find the renter to ownership ratio in Ohio
```

**Response:** 
```
📊 **Census: B25003_002E,B25003_003E for state:39**

**Ohio (39):**
- Owner-Occupied: 3,241,180 (67.1%)
- Renter-Occupied: 1,589,455 (32.9%)
```

## Capabilities

### Calculate State-Level Housing Metrics
Retrieves median home values, gross rent rates, owner-occupied counts, and vacancy percentages for all U.S. states.

### Compare County Market Trends
Gathers housing data (values, rent, ownership) across multiple counties within a single state for direct comparison.

### Generate Socioeconomic State Snapshots
Pulls a complete profile for a state that combines population metrics, income levels, and core demographic statistics alongside housing data.

### Run Custom Census Queries
Allows the agent to construct and execute highly specific API calls against any variable or geography supported by the Census Bureau.

## Use Cases

### Comparing Coastal vs. Inland Markets
A developer needs to know if a new project makes sense in Florida or Arizona. They first run `get_housing_by_state` to get the big picture, then use `get_county_profile` on three key counties in each state. This quickly identifies which region has lower vacancy rates and rising median home values.

### Building a Demographic Risk Assessment
An investment firm needs to vet a potential acquisition target. They start with `get_state_profile` for macro context, then use `query_census` to pull specific variables—like the percentage of population over 65 and average household size—to model future risk.

### Tracking Localized Rent Increases
A local policy researcher wants to prove that rent increases are outpacing wage growth. They use `get_housing_by_county` for several key counties and cross-reference the median gross rent data with income metrics from a custom `query_census` run.

### Identifying Population Decline Hotspots
A regional lender needs to find states where population is declining but housing inventory remains high. They start with `get_state_profile` and then use the specialized data in `query_census` to filter for low-growth areas that might need targeted lending products.

## Benefits

- See statewide trends immediately. Use `get_housing_by_state` to compare median rents or ownership rates across all 50 states in one query—you don't have to check them one by one.
- Drill down without leaving the workflow. Run `get_county_profile` and then use `get_housing_by_county` to keep comparing specific county market details within a parent state.
- Build full reports, not just single data points. The combination of `State Profile` and `query_census` lets you weave together housing metrics with deep demographic context (e.g., population shift vs. median income).
- Handle edge cases the pre-built tools miss. When you need a specific variable—like job growth per capita from 2015—use `query_census`. It covers everything available in the API.
- Save time compiling data sets. Instead of manually downloading and merging CSVs from multiple Census pages, your agent runs the query and spits out clean, structured JSON ready for use.

## How It Works

The bottom line is: you stop navigating Census websites and start asking direct questions about US population and housing trends.

1. First, you provide the agent with a scope (e.g., 'State X' or 'County Y') and define the variables needed (e.g., median rent, population count).
2. The agent selects the appropriate tool—like `get_housing_by_state` for broad views, or `query_census` if you need a specific variable not covered by pre-built tools.
3. You get back structured JSON data containing the requested metrics and demographics for your specified location. This output is ready to be written into reports.

## Frequently Asked Questions

**How do I get median rent data for all states using get_housing_by_state?**
Simply ask the agent to run `get_housing_by_state`. It provides home values, gross rent, ownership rates, and vacancies for every state in one structured output. You'll get a full comparative overview.

**Can I query census data that isn't listed in the tools using query_census?**
Yes. The `query_census` tool lets you specify custom variables (like B01003_001E) and target specific geographies, giving you access to virtually any dataset published by the Census Bureau.

**Is get_county_profile better than get_housing_by_county?**
It depends. Use `get_housing_by_county` if your focus is strictly on housing metrics (values/rent). Use `get_county_profile` when you need the full socioeconomic picture—demographics, income, and housing data combined.

**What kind of data does get_state_profile provide?**
It provides a complete state intelligence snapshot. This includes population metrics, income levels, and core demographics alongside the standard housing statistics, giving you broad context for analysis.

**How do I handle authentication when using query_census?**
You must use a free API key from the Census Bureau. The server requires this credential to run any custom queries. Always pass your generated API token as an environment variable or parameter during setup.

**What if I exceed rate limits when calling get_housing_by_state?**
If you hit a rate limit, the server returns a 429 error. Implement exponential backoff in your client logic; wait progressively longer periods before retrying the same request.

**Does get_county_profile allow me to filter by specific variables?**
Yes, you can narrow results using variable filters. You must specify which data points—like income or population density—you want included in the profile for that county.

**Is there a difference between get_housing_by_county and get_state_profile?**
The two tools target different scopes. Use `get_housing_by_county` when you need detailed housing stats (rent, ownership) for a specific local market. Use `get_state_profile` for broad demographics across the whole state.

**How are median home values calculated?**
The ACS asks respondents to estimate how much their property (house and lot, mobile home and lot, or condominium unit) would sell for if it were for sale. The median represents the middle value.

**Does 'Value' mean assessment or market value?**
It reflects an estimated market value by the owner, not assessed tax value or recent sales price.

**What does Gross Rent include?**
Gross rent includes the contract rent plus the estimated average monthly cost of utilities (electricity, gas, and water and sewer) and fuels.