Census Server

npm version CI codecov License: MIT Node.js Version

Node.js server implementing Model Context Protocol (MCP) for U.S. Census Bureau APIs.

Access Census Data Through AI

The Census MCP Server enables AI agents and applications to access comprehensive U.S. demographic and economic data from the Census Bureau. With this server, your AI can retrieve and analyze:

• American Community Survey (ACS) - Demographics, income, employment, education, housing
• Decennial Census (2020, 2010) - Complete population counts every 10 years
• Population Estimates - Annual population estimates by age, sex, race
• County Business Patterns - Business establishment counts, employment, payroll
• Economic Census - Comprehensive business statistics every 5 years
• Geographic Information - Land area, water area, centroid coordinates for any geography
• Census Geocoding - Convert addresses to coordinates and find Census geographies
• TIGERweb Boundaries - Retrieve actual geographic boundary polygons as GeoJSON
• Health Insurance Estimates - Health insurance coverage by county and demographic groups
• Public Sector Employment - Government employment and payroll statistics
• Poverty Statistics - Poverty estimates and median income for states and counties
• Rental Housing Finance - Financial and mortgage characteristics of rental properties
• Annual Business Survey - Business ownership by demographics (sex, ethnicity, race, veteran status)
• Community Resilience Estimates - Neighborhood social vulnerability and disaster resilience
• International Database - Global population data for 200+ countries (1950-2100)
• Quarterly Workforce Indicators - Employment, job creation, hires, separations, earnings by demographics and industry
• Business Dynamics Statistics - Job creation/destruction, business births/deaths, firm startups/shutdowns
• Geographic levels - National, state, county, tract, place, and more
• Historical data - Access data from 1950 to present, with projections to 2100

Whether you're building a demographic analysis tool, location intelligence application, policy research assistant, or any application that needs U.S. census data, the Census MCP Server provides direct access to official government statistics.

Usage

A Census API key is required to use this MCP server.

To get a free Census API key:

1. Visit https://api.census.gov/data/key_signup.html
2. Fill out the signup form with your organization and email
3. You'll receive your API key via email instantly

Installation

Using npm

npm install -g @bluerfalcon/census-mcp-server

Using npx (no installation required)

npx @bluerfalcon/census-mcp-server

Configuration

Claude Desktop Setup

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "census": {
      "command": "npx",
      "args": ["-y", "@bluerfalcon/census-mcp-server"],
      "env": {
        "CENSUS_API_KEY": "your_census_api_key_here"
      }
    }
  }
}

Environment Variables

Create a .env file in your project directory:

CENSUS_API_KEY=your_census_api_key_here
CENSUS_API_ENDPOINT=https://api.census.gov/data/  # optional

Available Resources

MCP Resources provide read-only access to Census vocabularies and metadata. Use these to discover available data before querying with tools.

1. ACS Variables Resource

Browse available variables for American Community Survey datasets.

URI Patterns:

• census://acs/2022/acs5/variables - All variables for 2022 ACS 5-year estimates
• census://acs/2021/acs1/variables - All variables for 2021 ACS 1-year estimates
• census://acs/2022/acs5/variables?group=B01001 - Variables in specific group (e.g., B01001 = Age/Sex)

Returns: JSON with variable codes, labels, concepts, and groups

Example Use:

Read census://acs/2022/acs5/variables?group=B19013 to see median income variables

2. Census Variables Resource

Browse available variables for various Census datasets. This is a generic resource that works across multiple Census APIs.

URI Patterns:

• census://variables/healthins/sahie - Health Insurance variables
• census://variables/popest - Population Estimates variables
• census://variables/idb/1year - International Database variables
• census://variables/govs - Public Sector Employment variables
• census://variables/poverty/saipe - Poverty Statistics variables
• census://variables/rhfs - Rental Housing Finance variables
• census://variables/abs - Annual Business Survey variables
• census://variables/cre - Community Resilience Estimates variables
• census://variables/cbp - County Business Patterns variables
• census://variables/ecnbasic - Economic Census variables
• census://variables/dec/pl - Decennial Census variables
• census://variables/qwi - Quarterly Workforce Indicators variables
• census://variables/bds - Business Dynamics Statistics variables

Returns: JSON with variable codes, labels, and descriptions for the specified dataset

Example Use:

Read census://variables/healthins/sahie to see all health insurance variables
Read census://variables/cre to see community resilience variables

3. State FIPS Codes Resource

Get all US state and territory FIPS codes.

URI: census://geography/states

Returns: JSON list of all states with FIPS codes, names, and abbreviations

Example Use:

Read census://geography/states to see all state codes

Available Tools

1. ACS Data Tool

Retrieve demographic and economic data from the American Community Survey (ACS).

Parameters:

• year: Year for ACS data (e.g., 2022)
• dataset: "acs1" (1-year estimates) or "acs5" (5-year estimates, default)
• variables: Array of Census variable codes (e.g., ["B01001_001E", "B19013_001E"])
• geography: Geographic level ("us", "state", "county", "tract", "place")
• state: State FIPS code (required for county/tract/place geographies)
• county: County FIPS code (required for tract geography)

Common Variables:

• B01001_001E - Total population
• B19013_001E - Median household income
• B25077_001E - Median home value
• B23025_005E - Unemployment count

Find more variables: ACS 5-Year Variables

2. Decennial Census Tool

Retrieve data from the U.S. Decennial Census (2020, 2010).

Parameters:

• year: "2020" or "2010"
• dataset: "pl" (redistricting), "dhc" (demographics), or "sf1" (summary file)
• variables: Array of variable codes (e.g., ["P1_001N", "P2_002N", "H1_001N"])
• geography: Geographic level ("us", "state", "county", "tract", "block group", "place")
• state: State FIPS code (required for sub-state geographies)
• county: County FIPS code (required for tract/block group)

Common Variables:

• P1_001N - Total population
• P1_003N - White alone population
• P1_004N - Black or African American alone
• P2_002N - Hispanic or Latino population
• H1_001N - Total housing units

Find more variables: 2020 Census Variables

3. Population Estimates Tool

Retrieve annual population estimates from the Population Estimates Program (PEP).

Parameters:

• year: Vintage year (2020-present, default: 2023)
• variables: Array of variables (default: ["POP"])
• geography: Geographic level ("us", "state", "county")
• state: State FIPS code (required for county)
• ageGroup: Age group code (optional filter)
• sex: "0" (both), "1" (male), "2" (female)
• hispanicOrigin: "0" (both), "1" (non-Hispanic), "2" (Hispanic)

Common Variables:

• POP - Population estimate
• AGE - Age group code
• SEX - Sex code
• POPGROUP - Race/ethnicity group
• HISP - Hispanic origin

Find more variables: PEP Variables

4. County Business Patterns Tool

Retrieve business statistics from County Business Patterns (CBP).

Parameters:

• year: Year for CBP data (1986-present, typically 2 years behind)
• variables: Array of variables (default: ["ESTAB", "EMP", "PAYANN"])
• geography: Geographic level ("us", "state", "county")
• state: State FIPS code (required for county)
• naics: NAICS industry code (2-6 digits)
• employmentSizeClass: Employment size code

Common Variables:

• ESTAB - Number of establishments
• EMP - Number of employees
• PAYANN - Annual payroll ($1,000s)
• PAYQTR1 - First quarter payroll ($1,000s)
• NAICS2017 - Industry code

Common NAICS Codes:

• 72 - Accommodation and food services
• 541 - Professional, scientific, and technical services
• 44-45 - Retail trade
• 62 - Health care and social assistance

Find more variables: CBP Variables

5. Economic Census Tool

Retrieve comprehensive business statistics from the Economic Census (every 5 years).

Parameters:

• year: "2017", "2012", or "2007"
• variables: Array of variables (default: ["ESTAB", "EMP", "RCPTOT", "PAYANN"])
• geography: Geographic level ("us", "state", "county", "metro area")
• state: State FIPS code (optional for state, required for county)
• county: County FIPS code (optional)
• naics: NAICS industry code (2-6 digits)
• sector: NAICS sector code (2 digits)

Common Variables:

• ESTAB - Number of establishments
• EMP - Number of employees
• RCPTOT - Sales/receipts/revenue ($1,000s)
• PAYANN - Annual payroll ($1,000s)
• VALADD - Value added ($1,000s)

Find more variables: Economic Census Variables

6. Geographic Information Tool

Retrieve geographic metadata and reference information from the Census Bureau Geographic Information API.

Parameters:

• year: Vintage year for geographic data (2020-present, default: 2023)
• variables: Array of geographic variables (see below for common options)
• geography: Geographic level ("us", "state", "county", "tract", "place", "congressional district")
• state: State FIPS code (required for county, tract, place, congressional district)
• county: County FIPS code (required for tract)

Common Variables:

• NAME - Geographic area name
• AREALAND - Land area (square meters)
• AREALAND_SQMI - Land area (square miles)
• AREAWATR - Water area (square meters)
• AREAWATR_SQMI - Water area (square miles)
• INTPTLAT - Internal point latitude (centroid)
• INTPTLON - Internal point longitude (centroid)

Example queries:

• "Get land and water area for California"
• "Show me the geographic metadata for all states"
• "What are the coordinates for the centroid of Los Angeles County?"

Find more info: Geographic Information API

7. Census Geocoding Tool

Convert addresses to coordinates or find Census geographies for any U.S. location. No API key required.

Parameters:

• searchType: "onelineaddress" (default), "address" (structured), or "coordinates" (reverse)
• address: Single line address string (for onelineaddress)
• street, city, state, zip: Structured address components (for address search)
• longitude, latitude: Coordinates (for reverse geocoding)
• returnGeographies: Return geographic hierarchies (default: true)
• benchmark: Benchmark version (default: Public_AR_Current)
• vintage: Geography vintage (default: Current_Current)

Returns:

• Coordinates (latitude/longitude)
• Matched address
• All Census geographies containing that location:
  • States, Counties, Places
  • Census Tracts, Block Groups, Blocks
  • Metropolitan Statistical Areas
  • Congressional Districts
  • ZIP Code Tabulation Areas

Example queries:

• "What Census tract is 1600 Pennsylvania Avenue in?"
• "Geocode this address: 123 Main St, San Francisco, CA"
• "What county contains coordinates 37.7749, -122.4194?"

8. TIGERweb Boundary Tool

Retrieve actual geographic boundary polygons as GeoJSON. No API key required.

Parameters:

• geographyType: "state", "county", "tract", "block group", or "place"
• state: State FIPS code or 2-letter abbreviation
• county: County FIPS code (required for tract/block group)
• tract: Census tract code (required for block group)
• geoid: Full GEOID to query specific feature
• name: Search by name (e.g., "California")
• vintage: Data vintage (default: Current)
• simplify: Return simplified geometries (default: false)

Returns:

• GeoJSON FeatureCollection with boundary polygons
• Can be used directly in mapping libraries
• Includes properties: GEOID, NAME, land area, etc.

Example queries:

• "Get the boundary polygon for California"
• "Show me the GeoJSON for Los Angeles County"
• "Get all Census tracts in San Francisco County"

Find more info: TIGERweb Documentation

9. Health Insurance Estimates Tool

Retrieve health insurance coverage estimates from the Small Area Health Insurance Estimates (SAHIE) program.

Parameters:

• year: Year for estimates (2006-2023, default: 2022)
• variables: Array of variables (see below for common options)
• geography: Geographic level ("us", "state", "county")
• state: State FIPS code (required for county, optional for state)
• county: County FIPS code (optional for specific county)
• ageCategory: Age group filter ("0": Under 65, "1": 18-64, "2": 40-64, "3": 50-64, "4": Under 19, "5": 21-64)
• incomeRange: Income category ("0": All, "1": ≤138% poverty, "2": ≤200%, "3": ≤250%, "4": ≤400%)
• raceEthnicity: Race/ethnicity ("0": All, "1": White non-Hispanic, "2": Black, "3": Hispanic)

Common Variables:

• NIC_PT - Number of people with health insurance
• NUI_PT - Number of people without health insurance
• PCTIC_PT - Percent with health insurance
• PCTUI_PT - Percent without health insurance
• NIPR_PT - Number in poverty range
• PCTLIIC_PT - Percent low-income with insurance

Example queries:

• "What percent of people in California have health insurance?"
• "Show me uninsured rates for all counties in Texas"
• "Get health insurance coverage for people under 65 in Florida"

Find more info: SAHIE Documentation

10. Public Sector Employment Tool

Retrieve government employment and payroll statistics from the Annual Survey of Public Employment & Payroll.

Parameters:

• year: Year for data (2017-2024, default: 2024)
• variables: Array of variables (see below for common options)
• geography: Geographic level ("us", "state")
• state: State FIPS code (optional for specific state)
• governmentType: Filter by government type ("state", "local", "combined")

Common Variables:

• TOT_EMP - Total employment (full-time + part-time)
• FT_EMP - Full-time employment
• PT_EMP - Part-time employment
• TOT_PAY - Total payroll (in thousands)
• FT_PAY - Full-time payroll (in thousands)
• PT_PAY - Part-time payroll (in thousands)
• TOT_HRS - Total hours worked
• FT_HRS - Full-time hours
• PT_HRS - Part-time hours

Example queries:

• "How many state government employees does California have?"
• "Show me total government employment and payroll by state"
• "What is local government employment in Texas?"
• "Compare state vs local government employees across all states"

Find more info: Public Employment Documentation

11. Poverty Statistics Tool

Retrieve poverty estimates and median household income from the Small Area Income and Poverty Estimates (SAIPE) program.

Parameters:

• year: Year for estimates (1989-2022, default: 2022)
• variables: Array of variables (see below for common options)
• geography: Geographic level ("us", "state", "county")
• state: State FIPS code (required for county, optional for state)
• county: County FIPS code (optional for specific county)

Common Variables:

• SAEPOVALL_PT - Poverty count (all ages)
• SAEPOVRTALL_PT - Poverty rate percentage (all ages)
• SAEPOV0_17_PT - Children in poverty (ages 0-17)
• SAEPOVRT0_17_PT - Child poverty rate (ages 0-17)
• SAEPOV5_17R_PT - School-age children in poverty (ages 5-17)
• SAEPOVRT5_17R_PT - School-age poverty rate (ages 5-17)
• SAEPOV0_4_PT - Young children in poverty (ages 0-4)
• SAEPOVRT0_4_PT - Young child poverty rate (ages 0-4)
• SAEMHI_PT - Median household income

Example queries:

• "What is the poverty rate in California?"
• "Show me child poverty rates for all counties in Mississippi"
• "Get poverty statistics and median income for all states"
• "Compare poverty rates across states"
• "What percent of children are in poverty in Texas counties?"

Find more info: SAIPE Documentation

12. Rental Housing Finance Tool

Retrieve rental housing finance data from the Rental Housing Finance Survey (RHFS).

Parameters:

• year: Year for data ("2015", "2018", "2021", default: "2021")
• group: Data group to retrieve (required, see below)
• propertySize: Filter by property size (optional, see below)

Data Groups:

• RHFS_PC - Property Configuration (building counts, unit counts, year built, etc.)
• RHFS_EX - Expenses (operating expenses, utilities, maintenance, etc.)
• RHFS_OM - Ownership and Management (ownership type, management, etc.)
• RHFS_IS - Income and Subsidies (rental income, government subsidies, etc.)
• RHFS_FM - Finances and Mortgage (mortgage status, refinancing, debt, etc.)
• RHFS_CI - Capital Improvements and Expenses (renovations, capital projects, etc.)

Property Size Filters:

• 0 - All properties (default)
• 1 - 1 unit properties
• 2 - 2-4 unit properties
• 3 - 5-24 unit properties
• 4 - 25-49 unit properties
• 5 - 50+ unit properties

Returns:

• Property counts and unit counts
• Detailed characteristics based on selected group
• Margins of error for estimates
• National-level data only (no state/county breakdown)

Example queries:

• "Get property configuration data for rental housing in 2021"
• "Show me rental housing expenses for properties with 5-24 units"
• "What are the financing characteristics of rental properties?"
• "Get income and subsidies data for single-unit rental properties"

Note: RHFS provides national-level statistics only and is available for years 2015, 2018, and 2021.

Find more info: RHFS Documentation

13. Annual Business Survey Tool

Retrieve business ownership data from the Annual Business Survey (ABS). Replaced the Survey of Business Owners (SBO) in 2017.

Parameters:

• year: Year for data (2017-2023, default: 2023)
• variables: Array of variables (see below for common options)
• geography: Geographic level ("us", "state", "county", "metro area")
• state: State FIPS code (required for county, optional for state)
• county: County FIPS code (optional for specific county)
• sex: Owner sex ("001": All, "002": Male, "003": Female)
• ethnicity: Owner ethnicity ("001": All, "002": Hispanic, "003": Non-Hispanic)
• race: Owner race ("00": All, "10": White, "20": Black, "30": American Indian/Alaska Native, "40": Asian, "50": Native Hawaiian/Pacific Islander, "60": Two or more races)
• veteran: Veteran status ("001": All, "002": Veteran, "003": Non-veteran)

Common Variables:

• FIRMPDEMP - Number of employer firms
• EMP - Number of employees
• PAYANN - Annual payroll (in thousands)
• RCPPDEMP - Receipts/sales (in thousands)
• FIRMPDEMP_PCT - Percent of employer firms
• EMP_PCT - Percent of employees
• PAYANN_PCT - Percent of payroll
• RCPPDEMP_PCT - Percent of receipts

Example queries:

• "How many businesses are owned by women in California?"
• "Get employer firms and employees for Hispanic-owned businesses by state"
• "Show me veteran-owned business statistics for all states"
• "What are the receipts for Asian-owned businesses in San Francisco County?"
• "Compare business ownership by demographic groups across states"

Find more info: ABS Documentation

14. Community Resilience Estimates Tool

Retrieve community resilience and social vulnerability data from the Community Resilience Estimates (CRE).

Parameters:

• year: Year for estimates ("2019", "2021", "2022", "2023", default: "2023")
• variables: Array of variables (see below for common options)
• geography: Geographic level ("us", "state", "county", "tract")
• state: State FIPS code (required for county and tract, optional for state)
• county: County FIPS code (required for tract, optional for specific county)

Common Variables:

• PRED0_PE - Percent with zero vulnerability factors (most resilient)
• PRED12_PE - Percent with 1-2 vulnerability factors (moderate)
• PRED3_PE - Percent with 3+ vulnerability factors (high vulnerability)
• PRED0_E - Count with zero vulnerability factors
• PRED12_E - Count with 1-2 vulnerability factors
• PRED3_E - Count with 3+ vulnerability factors
• POPUNI - Total population universe

Vulnerability Components (8 factors):

• Disability
• Single-parent households with children under 18
• Limited English proficiency
• Poverty
• No vehicle access
• Crowded housing (>1.5 persons per room)
• Group quarters (institutionalized population)
• Age vulnerability (under 5 or 65+ years)

Example queries:

• "What is the social vulnerability for all tracts in San Francisco County?"
• "Show me community resilience estimates for California counties"
• "Get neighborhood-level vulnerability data for census tracts in Los Angeles"
• "Which neighborhoods have the highest disaster vulnerability in my county?"
• "Compare resilience scores across states"

Perfect for: Real estate applications (Zillow-like), disaster preparedness, neighborhood risk assessment, emergency planning, community development.

Find more info: CRE Documentation

15. International Database Tool

Retrieve global population statistics from the U.S. Census Bureau International Database (IDB). Access population data for 200+ countries and territories worldwide from 1950 to 2100 (historical estimates and future projections).

Parameters:

• year: Year for population data (1950-2100)
• variables: Array of IDB variable codes (e.g., ["POP", "CBR", "E0"])
• country: Optional FIPS country code (e.g., "CH" for China, "IN" for India, "US" for United States)
• ageGroup: Optional age group filter (e.g., "0-4", "5-9", "10-14")
• sex: Optional sex filter (0 = Both sexes, 1 = Male, 2 = Female)

Common Variables:

• POP - Total population
• CBR - Crude birth rate (births per 1,000 population)
• CDR - Crude death rate (deaths per 1,000 population)
• E0 - Life expectancy at birth (years)
• GR - Population growth rate (percent)
• IMR - Infant mortality rate (deaths per 1,000 live births)
• MAB - Median age at birth (years)
• TFR - Total fertility rate (births per woman)
• NI - Natural increase (births minus deaths)
• NM - Net migration (immigrants minus emigrants)
• POP_DENS - Population density (persons per square kilometer)
• AREA_KM2 - Land area (square kilometers)

Example queries:

• "What is the current population and life expectancy for India?"
• "Show me birth rates and death rates for all countries in 2024"
• "Get population projections for Brazil from 2025 to 2050"
• "Compare fertility rates across African countries"
• "What is the population density and median age for China?"

Perfect for: International demographics, global population analysis, country comparisons, development indicators, migration studies, demographic projections.

Find more info: IDB Documentation

16. Quarterly Workforce Indicators Tool

Retrieve quarterly employment statistics from the Quarterly Workforce Indicators (QWI) program. Access 32+ economic indicators including employment levels, job creation/destruction, hires, separations, earnings, and turnover rates. Data available from 1990-present at state, county, metro area, and workforce investment board area levels.

Parameters:

• year: Year for QWI data (1990-present)
• quarter: Quarter (1-4)
• variables: Array of QWI variable codes (e.g., ["Emp", "HirA", "Sep", "EarnS"])
• geography: Geographic level (state, county, metro, wib)
• state: Optional state FIPS code (required for county geography)
• sex: Optional sex filter (0 = Both, 1 = Male, 2 = Female)
• agegrp: Optional age group (A00 = All, A01 = 14-18, A02 = 19-21, A03 = 22-24, A04 = 25-34, A05 = 35-44, A06 = 45-54, A07 = 55-64, A08 = 65-99)
• education: Optional education level (E0 = All, E1 = Less than high school, E2 = High school, E3 = Some college, E4 = Bachelor or advanced, E5 = Advanced degree)
• race: Optional race filter (A0 = All, A1 = White, A2 = Black, A3 = American Indian/Alaska Native, A4 = Asian, etc.)
• ethnicity: Optional ethnicity (A0 = All, A1 = Not Hispanic, A2 = Hispanic)
• industry: Optional NAICS industry code (e.g., "00" = All, "54" = Professional services)
• firmage: Optional firm age (0 = All, 1 = 0-1 years, 2 = 2-3 years, 3 = 4-5 years, 4 = 6-10 years, 5 = 11+ years)
• firmsize: Optional firm size (0 = All, 1 = 0-19 employees, 2 = 20-49, 3 = 50-249, 4 = 250-499, 5 = 500+)

Common Variables:

• Emp - Employment (number of jobs)
• EmpS - Stable employment (workers employed at firm for full quarter)
• HirA - Hires (all workers hired during quarter)
• Sep - Separations (all workers who separated during quarter)
• EarnS - Average earnings for stable workers
• EarnBeg - Beginning-of-quarter earnings
• EarnHirAS - Average earnings of hires
• Payroll - Total payroll
• TurnOvrS - Turnover rate (separations / average employment)
• HirAS - Hire rate (hires / average employment)
• SepS - Separation rate (separations / average employment)
• JC - Job creation (net employment gains at expanding establishments)
• JD - Job destruction (net employment losses at contracting establishments)

Example queries:

• "What are the employment levels and average earnings in San Francisco County for Q1 2023?"
• "Show me job creation and destruction rates for all states in Q4 2022"
• "Get hiring rates for professional services (NAICS 54) by state for Q2 2023"
• "Compare average earnings between male and female workers in California for Q3 2023"
• "What are the turnover rates by age group in New York metro areas for Q1 2024?"
• "Show me employment by education level for all counties in Texas for Q2 2023"
• "Get job creation in young firms (0-1 years) for all states in Q4 2022"

Perfect for: Job market analysis, wage trends, employment dynamics, labor market research, workforce planning, economic development, evaluating areas for relocation.

Find more info: QWI Documentation

17. Business Dynamics Statistics Tool

Retrieve annual business dynamics statistics showing job creation, job destruction, establishment births/deaths, and firm startups/shutdowns. Track economic dynamism and business health from 1978-2023 at national, state, and metro/micro area levels.

Parameters:

• year: Year for BDS data (1978-2023)
• variables: Array of BDS variable codes (e.g., ["ESTABS", "JOB_CREATION", "JOB_DESTRUCTION"])
• geography: Geographic level (us, state, metro)
• state: Optional state FIPS code (required for metro geography, optional for state)
• naics: Optional NAICS industry code (e.g., "00" = All, "54" = Professional services)
• metro: Optional metro filter (0 = All, 1 = Filter applied, M = Metropolitan, N = Micropolitan/non-metro)
• fage4: Optional firm age (a) 0 = Startups, b) 1-5, c) 6-10, d) 11-15, e) 16-20, f) 21-25, g) 26+)
• fsize: Optional firm size (a) 1-4 employees, b) 5-9, c) 10-19, d) 20-49, e) 50-99, f) 100-249, etc.)
• eage4: Optional establishment age (a) 0 = New, b) 1-5, c) 6-10, d) 11-15, etc.)
• esize: Optional establishment size (a) 1-4 employees, b) 5-9, c) 10-19, d) 20-49, etc.)

Common Variables:

• ESTABS - Number of establishments
• ESTABS_ENTRY - New establishments (births)
• ESTABS_EXIT - Closing establishments (deaths)
• JOB_CREATION - Gross jobs created
• JOB_DESTRUCTION - Gross jobs destroyed
• NET_JOB_CREATION - Net job change (creation - destruction)
• FIRMS - Number of firms
• FIRMS_ENTRY - New firms (startups)
• FIRMS_EXIT - Closing firms (shutdowns)
• EMP - Employment level
• JOB_CREATION_BIRTHS - Job creation from new establishments
• JOB_CREATION_CONTINUERS - Job creation from expanding establishments
• JOB_CREATION_RATE - Job creation rate (as percentage)
• JOB_DESTRUCTION_DEATHS - Job destruction from closing establishments
• JOB_DESTRUCTION_CONTINUERS - Job destruction from contracting establishments
• JOB_DESTRUCTION_RATE - Job destruction rate (as percentage)

Example queries:

• "What were the job creation and destruction rates for California in 2023?"
• "Show me firm startups and shutdowns by state for 2022"
• "Get establishment births and deaths for professional services (NAICS 54) for all states in 2023"
• "Compare business dynamics between metropolitan and non-metropolitan areas in Texas for 2022"
• "What is the net job creation in young firms (0-5 years old) for all states in 2023?"
• "Show me job creation rates by establishment size in New York for 2022"
• "Get business dynamics statistics for the tech sector (NAICS 51, 54, 55) by state for 2023"
• "What's the startup rate and job creation from new firms in Florida metro areas for 2022?"

Perfect for: Business environment analysis, economic vitality assessment, entrepreneurship research, job market dynamics, evaluating economic health when considering relocation.

Find more info: BDS Documentation

Example Prompts

Try these prompts with Claude Desktop after setup:

Demographics & Population

• "What is the total population of California in 2020?"
• "Get the current 2023 population estimates for all states"
• "Show me median household income for all states in 2022"
• "What's the Hispanic population in Texas counties in 2020?"
• "Get population by age and sex for New York state"

Housing & Economic Data

• "What is the median home value in San Francisco (state 06, county 075)?"
• "Compare unemployment rates across all U.S. states"
• "Show me median household income for all states"
• "Get property configuration data for rental housing in 2021"
• "Show me rental housing expenses for properties with 5-24 units"
• "What are the financing characteristics of rental properties?"

Poverty & Income

• "What is the poverty rate in California?"
• "Show me child poverty rates for all counties in Mississippi"
• "Get poverty statistics and median income for all states"
• "Compare poverty rates across states"
• "What percent of school-age children are in poverty in Texas?"
• "Show me poverty data for counties in Florida"

Business Statistics

• "How many restaurants (NAICS 72) are in California?"
• "Get employment and payroll for tech companies (NAICS 541) by state"
• "Show me retail establishments in New York state"
• "What's the total employment in professional services in 2022?"
• "Get Economic Census data for manufacturing (NAICS 31-33) by state"

Comparisons & Analysis

• "Compare population growth across states from 2020 to 2023"
• "Show me the difference between 2020 census and 2023 population estimates for California"
• "Compare business establishments across states in accommodation and food services"

Geocoding & Geography

• "What Census tract is 1600 Pennsylvania Avenue NW, Washington DC in?"
• "Geocode 350 Fifth Avenue, New York, NY and tell me what county it's in"
• "What geographies contain coordinates 37.7749, -122.4194?"
• "Get the boundary polygon for California as GeoJSON"
• "Show me the geographic boundaries for all counties in Texas"
• "Get the Census tract boundaries for San Francisco County"
• "What is the land area of Texas?"
• "Show me the geographic metadata for all states including land and water area"
• "Get the centroid coordinates for Los Angeles County"

Health & Social Services

• "What percent of people in California have health insurance?"
• "Show me uninsured rates for all counties in Texas"
• "Get health insurance coverage for people under 65 in Florida"
• "Compare health insurance rates across states for low-income populations"
• "What is the uninsured rate for children in Arizona?"

Government & Public Sector

• "How many state government employees does California have?"
• "Show me total government employment and payroll by state"
• "What is local government employment in Texas?"
• "Compare state vs local government employees across all states"
• "Get full-time and part-time government employment for New York"

Business Ownership & Demographics

• "How many businesses are owned by women in California?"
• "Get employer firms and employees for Hispanic-owned businesses by state"
• "Show me veteran-owned business statistics for all states"
• "What are the receipts for Asian-owned businesses in San Francisco County?"
• "Compare business ownership by demographic groups across states"
• "How many employees work at Black-owned businesses in Texas?"

Community Resilience & Neighborhood Risk

• "What is the social vulnerability for all tracts in San Francisco County?"
• "Show me community resilience estimates for California counties"
• "Get neighborhood-level vulnerability data for census tracts in Los Angeles"
• "Which neighborhoods have the highest disaster vulnerability?"
• "Compare resilience scores across states"
• "Show me the percent of people with 3+ vulnerability factors by tract"
• "What neighborhoods are most prepared for disasters?"

International / Global Demographics

• "What is the current population of China?"
• "Show me life expectancy trends for India from 2000 to 2024"
• "Compare birth rates and death rates across all countries in 2024"
• "What are the population projections for Brazil through 2050?"
• "Get fertility rates for all African countries"
• "Show me median age and population density for European countries"
• "What countries have the highest infant mortality rates?"

Employment & Job Market (Quarterly Workforce Indicators)

• "What are the employment levels and average earnings in San Francisco County for Q1 2024?"
• "Show me job creation rates for all states in Q4 2023"
• "Get hiring and separation rates for professional services by state for Q2 2024"
• "Compare average earnings between male and female workers in California for Q3 2023"
• "What are the turnover rates by age group in New York metro areas?"
• "Show me employment by education level for all counties in Texas for Q2 2024"
• "Get job creation in young firms (0-1 years) for California for Q1 2024"
• "What are the wage trends for tech workers in Seattle metro area?"

Business Dynamics & Economic Vitality

• "What were the job creation and destruction rates for California in 2023?"
• "Show me firm startups and shutdowns by state for 2023"
• "Get establishment births and deaths for professional services for all states in 2023"
• "Compare business dynamics between metro and non-metro areas in Texas for 2023"
• "What is the net job creation in young firms (0-5 years old) for all states in 2023?"
• "Show me job creation rates by establishment size in New York for 2023"
• "Get business dynamics for the tech sector by state for 2023"
• "What's the startup rate in Florida metro areas for 2023?"

Development

Setup

git clone https://github.com/mattpodwysocki/census-mcp-server.git
cd census-mcp-server
npm install
cp .env.example .env
# Edit .env and add your CENSUS_API_KEY

Build

npm run build

Inspect Server

npm run inspect:dev

Testing

Run the unit test suite:

npm test

Run tests with coverage report:

npm run test:coverage

Run tests in watch mode:

npm run test:watch

API Reference

The Census API provides access to numerous datasets. This MCP server currently supports:

• American Community Survey (ACS) - 1-year and 5-year estimates
  • Documentation
• Decennial Census - 2020, 2010 complete counts
  • Documentation
• Population Estimates Program (PEP) - Annual estimates
  • Documentation
• County Business Patterns (CBP) - Annual business statistics
  • Documentation
• Economic Census - Comprehensive business data (every 5 years)
  • Documentation
• Geographic Information API - Geographic metadata (land area, water area, coordinates)
  • Documentation
• Census Geocoding Services - Address to coordinates, reverse geocoding (no API key)
  • Documentation
• TIGERweb GeoServices - Geographic boundaries as GeoJSON (no API key)
  • Documentation
• Small Area Health Insurance Estimates (SAHIE) - Health insurance coverage by county
  • Documentation
• Annual Survey of Public Employment & Payroll - Government employment and payroll
  • Documentation
• Small Area Income and Poverty Estimates (SAIPE) - Poverty estimates and median income
  • Documentation
• Rental Housing Finance Survey (RHFS) - Rental property financial and mortgage characteristics
  • Documentation
• Annual Business Survey (ABS) - Business ownership by demographics (replaced SBO)
  • Documentation
• Community Resilience Estimates (CRE) - Social vulnerability and disaster resilience
  • Documentation
• International Database (IDB) - Global population estimates and projections (1950-2100)
  • Documentation

Geographic Identifiers

State FIPS Codes

States are identified by 2-digit FIPS codes:

• 01 - Alabama
• 06 - California
• 12 - Florida
• 36 - New York
• 48 - Texas

Full list: State FIPS Codes

County FIPS Codes

Counties are identified by 3-digit codes within each state.

NAICS Industry Codes

Industries are classified using the North American Industry Classification System (NAICS):

• 2-digit: Sector (e.g., "72" = Accommodation and Food Services)
• 3-digit: Subsector (e.g., "721" = Accommodation)
• 4-digit: Industry Group (e.g., "7211" = Traveler Accommodation)
• 6-digit: Industry (e.g., "721110" = Hotels and Motels)

Full list: NAICS Codes

Data Usage & Privacy

What data is sent to Census APIs

When you use the MCP server tools, the following data is sent to Census Bureau APIs:

• API key
• Query parameters (year, variables, geography)
• Geographic identifiers (state, county codes)
• Industry codes (NAICS)

Your privacy

• Local execution: All API calls are made directly from your environment to Census APIs
• API key security: Your Census API key remains on your local machine
• No data storage: This MCP server does not store, log, or collect any of your data
• Direct communication: No intermediary server between you and Census APIs

Third-party data usage

• Census Bureau's privacy policy: Privacy Policy
• API terms: Standard Census API terms apply to all requests

Contributing

We welcome contributions! Here's how you can help:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/your-feature-name
3. Make your changes and add tests
4. Run the test suite: npm test
5. Lint your code: npm run lint:fix
6. Commit your changes: git commit -m "Add your feature"
7. Push to your fork: git push origin feature/your-feature-name
8. Open a Pull Request

Development Guidelines

• Add unit tests for new features
• Update README documentation for new tools
• Follow existing code style and patterns
• Run npm run lint and npm test before committing
• Write clear commit messages

Ideas for Contributions

• Add more Census datasets and tools
• Improve error handling and validation
• Add more comprehensive examples
• Improve documentation
• Report bugs and suggest features

Support

• GitHub Issues: Report bugs and feature requests
• Census API Support: Census Developer Support
• Discussions: GitHub Discussions

License

MIT License - see LICENSE for details

Resources

• Census Data API User Guide
• Available Census APIs
• Model Context Protocol