us-census-bureau-data-api

The U.S. Census Bureau Data API MCP server exposes tools that connect AI assistants to Census data. It primarily pulls data from the Census Data API and caches or aggregates results locally in a Postgres database to enable fast, contextual queries when assisting users. The server is designed to be queried via MCP client calls (tools/list, tools/call, prompts/list, prompts/get), allowing an AI to discover available datasets, fetch geographic metadata, and retrieve aggregate data through a consistent, structured interface. To use it, configure your MCP client to point at the server (often via a docker-based or shell-based bootstrap script) and provide a valid Census API key through the environment, as shown in the example configuration. Once connected, you can list datasets, fetch dataset geography, and request aggregated data by invoking the corresponding tools with the required arguments.

Prerequisites:

• Docker (Desktop) installed
• Node.js 18+ installed if you plan to run npm scripts locally
• Access to a Census API key

Installation steps:

1. Clone or download the repository to your local machine.
2. Ensure Docker is running.
3. If you want to populate the local database and seed data on first run, follow the project’s recommended setup script using docker compose. Example:

docker compose --profile prod run --rm census-mcp-db-init sh -c "npm run migrate:up && npm run seed"

4. Start the MCP server locally using the provided scripts or Docker configuration. If you’re using the example MCP connect script, run:

# Example (adjust paths as needed):
bash /Path/To/Server/us-census-bureau-data-api-mcp/scripts/mcp-connect.sh

5. Ensure you supply a Census API key via environment variable CENSUS_API_KEY when starting the server through your MCP client configuration. You can test access by listing tools and making a sample call through your MCP client.

Notes:

• If you modify environment variables or paths, update the mcp-connect.sh invocation accordingly.
• For production, follow the repository’s guidance on rebuilding the production environment after releases (prod:down and prod:build).

Tips and common issues:

• A valid Census API key is required for MCP server tests and data fetching.
• When running in development, you may disable verbose logging unless debugging by setting DEBUG_LOGS accordingly.
• Ensure the correct environment variable CENSUS_API_KEY is passed to the MCP server so that downstream requests to the Census Data API are authorized.
• When deploying with Docker, keep the database migrations and seeds in sync with the server version to avoid schema mismatches.
• If you encounter connection issues from the MCP client, verify the path to the mcp-connect.sh script and confirm that Docker networking allows the client to reach the MCP server.
• Update the npm scripts and environment per the project’s release notes when upgrading to new versions.