census-mcp

Remote MCP server exposing US Census (ACS 5-year) and FEMA flood data. Works as a connector in both Claude and ChatGPT. Separate service from dmap-ai-mcp (own folder, own port 8020, own repo) — the drought server is not touched.

Tools

Related MCP server: civic-library-mcp

Run locally

cd census-mcp
python -m venv venv && venv\Scripts\activate    # Windows
pip install -r requirements.txt
set CENSUS_API_KEY=your_key                     # free: https://api.census.gov/data/key_signup.html
set MCP_ACCESS_KEY=some-long-random-secret
uvicorn server:app --port 8020

Smoke test (should return the tool list):

curl -s -X POST "http://127.0.0.1:8020/census-mcp/some-long-random-secret/" \
  -H "Content-Type: application/json" -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

GitHub

cd census-mcp
git init
git add .
git commit -m "census-mcp: initial version"
# create an empty repo named census-mcp at github.com/new (private is fine), then:
git remote add origin https://github.com/sohrab4748/census-mcp.git
git push -u origin main

Never commit real keys — they live only in the systemd unit / environment.

Deploy on the DigitalOcean droplet

ssh your-droplet
sudo git clone https://github.com/sohrab4748/census-mcp.git /opt/census-mcp
cd /opt/census-mcp
sudo python3 -m venv venv && sudo venv/bin/pip install -r requirements.txt

sudo cp deploy/census-mcp.service /etc/systemd/system/
sudo nano /etc/systemd/system/census-mcp.service   # put real CENSUS_API_KEY + MCP_ACCESS_KEY
sudo systemctl daemon-reload && sudo systemctl enable --now census-mcp
sudo systemctl status census-mcp                   # should be active (running)

Then add the contents of deploy/nginx-snippet.conf inside the existing server {} block for droughtanalysis.com and run sudo nginx -t && sudo systemctl reload nginx.

Your connector URL becomes:

https://droughtanalysis.com/census-mcp/<MCP_ACCESS_KEY>/

The secret in the URL is the access control (chosen for launch); anyone without it gets 404. Rotate it by changing the env var and restarting.

Connect it

Claude (claude.ai or desktop): Settings → Connectors → Add custom connector → paste the URL above.

ChatGPT: Settings → Apps & Connectors → enable Developer mode → Create → paste the same URL (no auth). Then enable it in a conversation or attach it to a custom GPT.

Notes / roadmap

• ACS vintage is pinned via ACS_YEAR (default 2023); bump when 2024 5-year drops.

• find_cells with area="USA" starts at county level by design — block-group scans of all 50 states are too slow for a single tool call.

• Census and FEMA requests share one connection-pooled HTTP client. Transient transport failures, HTTP 429 responses, and 5xx responses are retried up to three times with exponential backoff.

• Coordinates, ACS variable IDs, and hierarchical FIPS components are validated before an upstream request. ACS calls accept at most 45 variables.

• Upstream payloads are bounded (8 MiB normally and 32 MiB for the cached ACS variable catalog). The catalog is downloaded once per process, including when multiple first-use requests arrive concurrently.

• Install requirements-dev.txt and run python -m pytest -q for the fully mocked test suite; tests never call the live Census or FEMA APIs.

• Later: real OAuth, usage metering, per-user favorites ("favorite reports"), more datasets (Decennial, County Business Patterns, TIGER boundaries). "# census-mcp"