US Census Data

Inspiration

This project was inspired by an Elasticsearch lab by Alex Salgado which develop an MCP server using Elasticsearch for real health data.

What it does

This project retrieves demographic information from the U.S. Census API, loads a GeoJSON file containing the geographical features of all 51 U.S. states, ingests data through the Bulk API, and creates an Elasticsearch index using a predefined mapping. It incorporates both SF1 and CSA datasets to provide population, income, and household statistics. The project also includes a Model Context Protocol (MCP) server for querying census data stored in Elasticsearch, with helper functions, MCP resources, MCP tools, and MCP prompts.

How we built it

This project is built using the uv python package and project manager. From the console, I run a Python script that ingests data and another script to start the MCP server. All documents are ingested into the Elasticsearch deployment, enabling conversational interaction with an agent to query U.S. Census data. Last but not least, I can visualize results on a geospatial map for actionable insights.

Challenges we ran into

Some challenges included merging two U.S. Census datasets and integrating a GeoJSON file for geographic features. Additionally, combining the merged dataset with the geographic features into a single Elasticsearch index. Another challenge involved configuring the choropleth visualization and making sure the geospatial shapes matched the statistical dataset through the shared state field.

Accomplishments that we're proud of

I’m proud to have developed an LLM MCP backend service that can carry out conversations with an agent to explore U.S. demographic data. I also really enjoyed building choropleth visualizations that highlight key metrics such as population, median age, income, and home values.

What we learned

I’ve learned how to manage Elasticsearch data and work with the three core MCP primitives—resources, tools, and prompts—to build a complete system that connects LLMs to external functionality.

What's next for US Census Data

This project could be extended by dynamically fetching data from the API, allowing a user to instruct the agent to retrieve demographic information for a specific year.

Built With

• apis
• elasticsearch
• geopandas
• kibana
• mcp-server
• mcp.server.fastmcp
• python