What is Mcp Census

MCP Census is a server that harnesses U.S. Census Bureau tools to facilitate interoperability for large language models (LLMs). It is designed as a work-in-progress, focusing on enhancing access to census data through various client applications.

Use cases

MCP Census can be utilized for querying detailed demographic information, such as the population age distribution in specific counties, racial/ethnic breakdowns, and generating CSV reports containing census data for regions like New York State. It works well alongside MCP Clients like Claude Desktop or Cursor.

How to use

To use MCP Census locally, start by setting up the environment with uv for dependency management. Users need to run three applications (MCP server, Agent, and Phoenix) and configure their API keys. The Gradio MCP server is initialized through a specific command that serves the application locally, allowing for data queries.

Key features

Key features include the ability to interactively query census data, generate reports (like CSV files), support for multiple ages and demographic breakdowns, and a structured observability framework to monitor agent behavior. It also integrates directly with external APIs for seamless data access.

Where to use

MCP Census can be effectively used in various environments, including local setups on personal machines or deployed via platforms such as Hugging Face Spaces, making it versatile for both individual and group projects in data analysis and research.

title: 🏘️ Mcp Census
emoji: 🏘️
colorFrom: yellow
colorTo: indigo
sdk: gradio
sdk_version: 5.33.0
python_version: 3.13
app_file: gradio_app.py
pinned: false
short_description: MCP server leveraging U.S. Census Bureau tooling

mcp-census

A work-in-progress MCP server leveraging U.S. Census Bureau tooling for LLM interoperability.

A deployed interactive version of the mcp server is available at https://abrezey-mcp-census.hf.space/. A deployed census MCP server is available at https://abrezey-mcp-census.hf.space/gradio_api/mcp/sse. Pushes to the main branch of this repo will trigger a redeployment of these resources via GitHub Actions.

This repo was built for the Gradio/Hugging Face Agents MCP Hackathon.

Example usage

Right now, we recommend using mcp-census in conjunction with a MCP Client like Claude Desktop or Cursor. If you prefer to run your own client application, check out Local Agent Quickstart.

What is the population of Hennepin County, MN for those who are 65 and older?

https://github.com/user-attachments/assets/c979b9aa-8299-4eec-ad32-362d28ced5e4

What is the racial/ethnic breakdown of Yolo County?

https://github.com/user-attachments/assets/d7c34ecb-4503-4bde-a7eb-b865a6f076c8

Lookup data from the US 2020 Decennial Census and provide a CSV containing data about the number of housing units, total population, and median age for all counties in New York State. For the column containing the county identifier, please provide a complete FIPS containing the state and county as a joined value.

https://github.com/user-attachments/assets/cffd80f0-0830-4534-ab1a-9574608967ad

Local MCP server quickstart

We suggest using uv to manage dependencies, but you can install the required packages directly from the pyproject.toml file

You need to start all three applications (MCP server, Agent, Phoenix) for the system to work at the moment.

API Key

cp .env.example .env

Then fill out your API keys

To request a census API key, visit https://api.census.gov/data/key_signup.html
To request a Hugging Face token, visit https://huggingface.co/docs/hub/security-tokens

The MCP server does not require a Hugging Face token, though it becomes useful during agent development.

Gradio MCP server

uv run --group gradio-deployment python gradio_app.py

Assuming you have no other Gradio applications running, this will serve your MCP server at http://localhost:7860/gradio_api/mcp/sse

To update dependencies for the Gradio deployment

uv export --group gradio-deployment > requirements.txt

Fast MCP server

In dev mode

uv run mcp dev server.py

To install in your local Claude Desktop app

uv run mcp install server.py --with-editable .

Local Agent Quickstart

Agent (and MCP client)

uv run --group agent python agent.py

Observability

When debugging Agents, observability is key. The agent is currently configured to send logs to a phoenix server.

uv run python -m phoenix.server.main serve

The agent will not work without this server running.

MCP architecture

Possible improvements

Evaluation

• We recommend starting here to provide a strong benchmark with which to evaluate improvements.
• MCP server tools can be evaluated via unit tests. Agentic behavior can be evaluated on criteria described here and emerging frameworks such as RAGAS.

MCP Client

• Rather than build tool sets for every Census dataset (decennial, american community survey, etc.), it may be more comprensive to build tooling around the machine readable dataset discovery tool.
• The Census Bureau publishes myriad documentation. Enabling semantic retrieval via RAG should provide agents with information to better respond to user queries.

Agent

• Agentic Behavior can be fine tuned via foundation model choice, prompting as well as introduction of additional tooling such as data exporting. The exact optimizations may depend on intended use case.
• Improved citations of census bureau documentation.