Census-MCP-Server

> Disclaimer: This is an independent project and is not officially affiliated with or endorsed by the U.S. Census Bureau. All data is sourced from publicly available Census Bureau APIs with endpoint versions pinned to current releases. No Census seals, logos, or branding are used in compliance with Census graphic standards. Any views expressed are those of the authors and not those of the U.S. Census Bureau.

Census in Your Pocket 📱

Work in Progress - Building an AI interface for Census data

Turn any AI assistant into your personal Census data expert. Ask questions in plain English, get accurate demographic data with proper interpretation and context.

Before: "I need ACS Table B19013 for FIPS code 24510 with margin of error calculations..."
After: "What's the median income in Baltimore compared to Maryland?"

The Problem

U.S. Census data is incredibly valuable but has a steep learning curve for non-specialists. Even experienced researchers struggle with geographic hierarchies, variable naming conventions, margin of error calculations, and knowing which data combinations actually work. In our experience, the biggest impediment to demographic analysis is often just figuring out how to get the right data in the first place.

Vision: Democratizing America's Data

Today: Census data influences billions in government spending and policy decisions, but accessing it effectively requires specialized knowledge that creates barriers for many potential users.

Tomorrow: City council members fact-check claims in real-time during meetings. Journalists get demographic context while writing stories. Nonprofits understand their communities without hiring statisticians. Researchers spend time analyzing instead of wrestling with APIs.

The Goal: Make America's most valuable public dataset as easy to use as asking a question.

How It Works

graph LR
    A["User Question: Poverty rate in rural counties?"] --> B["AI Assistant (ChatGPT, Claude, Gemini, etc.)"]
    B --> C["Census MCP Server (Domain Expertise Layer)"]
    C --> D["Python Census Package (censusdata, etc.)"]
    C --> H["Metadata Endpoints (follows collection path, e.g., /data/{year}/acs/acs5/{collection}/variables.json where {collection} = profile, detailedprofile, comparisonprofile, or subject)"]
    D --> E["Census Bureau API (Official Data Source)"]
    H --> E
    E --> D
    E --> H
    D --> C
    H --> C
    C --> F["Interpreted Results + Context + Caveats"]
    F --> B
    B --> G["User gets accurate answer with proper interpretation"]
    
    style C fill:#e1f5fe
    style F fill:#f3e5f5

Note: Complex queries may require multiple API calls and batch orchestration

Analogies: What This Is Like

GPS for Data Navigation: Instead of needing to read maps and calculate routes manually, you just say where you want to go and the system handles the navigation.

Having a Census Expert in Your Pocket: Like having a demographer sitting next to you who instantly knows which data to pull, how to interpret it properly, and what caveats to mention.

What Stripe Did for Payments: Stripe made online payments simple by hiding complexity behind a clean interface. We aim to make Census data simple by hiding complexity behind natural language.

Current Scope: Starting with ACS

Phase 1 Focus: American Community Survey (ACS) 5-year estimates
- Most flexible annual demographic dataset
- Well-supported by existing Python packages
- Covers demographics, economics, housing, social characteristics
- Note: 5-year estimates include every census tract and county; 1-year estimates do not

Future Expansion: Additional surveys (SIPP, Economic Census), geographic visualizations, multi-agency integration

What We're Building

Smart Query Translation: Convert natural language questions into proper Census API calls, handling geography codes (including disambiguation of ambiguous place names like "Springfield, IL" vs FIPS codes - disambiguation based on GNIS + TIGER place class with user prompting when duplicates exist, surfacing state FIPS like "Kansas City, MO 29-38000 or Kansas City, KS 20-36000?"), variable selection (mapping B19013_001E → "Median household income"), and valid combinations.

Domain Knowledge Integration: Encode expertise about which data sources are appropriate for different questions, when estimates are reliable, and how to interpret results correctly.

Statistical Context: Automatically include margins of error with proper propagation hierarchy (ACS Generalized Variance Function for supported tables → replicate weights if available via local summary file download → conservative quadratic formula for API-only derived statistics), suppression handling (if estimate in {(X), -666666666, -333333333, } → treat as suppressed), and CV calculations with numeric guardrails and vintage lag considerations (CV computation uses latest published GVF - CVs for current vintage lag by ~1 year).

- Basic Demographics: "Population of Miami-Dade County"
- Comparative Analysis: "Compare unemployment rates between Detroit and Pittsburgh" (derived from B23025 variables)
- Housing Statistics: "How many renter-occupied units in Phoenix?"
- Geographic Patterns: "Rural poverty rates across the Southeast"
- Time Series: "How has median income changed in Austin since 2015?"

Note: Complex definitions like "vulnerable populations" will be clearly specified using established indices (e.g., CDC Social Vulnerability Index).

Built on: Model Context Protocol (MCP) - Note: MCP is experimental and subject to breaking changes

Data Integrity: Returns only published aggregates with proper suppression checking (if estimate in {(X), -666666666, -333333333, } → suppressed), never record-level data

Quick Start

🚧 Implementation in Progress

Prerequisites

Future Installation

git clone https://github.com/yourusername/Census-MCP-Server.git
cd Census-MCP-Server
pip install -r requirements.txt
python mcp_server.py

Contributing

This project aims to democratize access to public data. We welcome contributions in:

- Domain expertise improvements (especially from Census data veterans)
- Statistical methodology implementation
- Additional data source integration
- Documentation and examples
- Testing with real-world use cases

Roadmap

- [ ] Phase 1: ACS 5-year estimates with basic query translation
- [ ] Phase 2: Statistical rigor (MOE propagation using ACS Generalized Variance Function for ratios, CV ≥ 15% flagged as unreliable, CV ≥ 30% suppressed for small-denominator rates - GVF lag means CVs for current year appear the following spring)
- [ ] Phase 3: Additional Census surveys (SIPP, Economic Census with per-sector logic and version pinning - 2017 vs 2022 vs upcoming ECB schemas, PEP - Population Estimates Program)
- [ ] Phase 4: Geographic visualization capabilities
- [ ] Phase 5: Multi-agency data integration (BLS uses CBSA codes, BEA uses BEA regions - non-trivial crosswalks required)

Acknowledgments

Built on the excellent work of:
- censusdata Python package
- tidycensus R package (inspiration)
- The dedicated teams at the U.S. Census Bureau who collect and maintain this vital public data

---

<pre>
RPC DCE RDF
↓ ↓ ↓
CORBA DCOM OWL
↓ ↓ ↓
└─→ SOAP ←┘ SPARQL
↓ ↓
REST Knowledge Graphs
↓ ↓
GraphQL ↓
↓ ↓
MCP ←─────────────→ LLMs
</pre>

"The patterns never really die, they just get better UX"