Census MCP Server
Taliawedged117/census-mcp-server
Consulte dados do Census Bureau diretamente no Claude com 7 ferramentas MCP
Ver no GitHubServidor MCP que fornece acesso aos dados do U.S. Census Bureau, permitindo consultas de variáveis, datasets e geografias. Expõe 7 ferramentas para descoberta de dados, busca de variáveis, resolução de geografias e comparação entre regiões via STDIO ou HTTP.
Instalação
npx convez-ai Taliawedged117/census-mcp-server1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Pesquisa demográfica e análise populacional
- Comparação de métricas socioeconômicas entre regiões
- Resolução de endereços para identificadores geográficos do Census
Veredito

MCP server bem estruturado para integração de dados Census em fluxos Claude. Cobertura completa do workflow de dados (descoberta, busca, consulta, comparação) com suporte a múltiplos protocolos de transporte. Recomendado para análises demográficas e pesquisa baseada em dados públicos.
README
A tradução para o português deste README ainda está na fila.
Public Hosted Server: https://census.caseyjhand.com/mcp
Tools
7 tools covering the full Census data workflow — from dataset discovery and variable search through geography resolution and ranked comparisons:
| Tool | Description |
|---|---|
census_list_datasets | Browse available Census Bureau datasets (ACS5, ACS1, Population Estimates, Decennial) with vintage years and dataset codes. |
census_list_geographies | List the geography levels supported by a dataset and year, with parent requirements and example FIPS values. |
census_search_variables | Keyword search across variable labels and concept groups. Returns estimate and margin-of-error codes together. |
census_get_variable | Fetch full metadata for one or more variable codes — label, concept, predicate type, universe, MOE sibling. |
census_resolve_geography | Convert place names (e.g., "King County, WA") or street addresses to Census FIPS identifiers via TIGERweb and Census Geocoder. |
census_query_data | Query a Census dataset for variables at a specific geography. Returns estimates with MOE, suppression codes resolved to readable reasons. |
census_compare_geographies | Rank and compare variables across multiple geographies — all counties in a state, all states nationally, or a named set. Sorted table output. |
census_list_datasets
Browse available Census Bureau datasets.
- Returns dataset codes, names, descriptions, and available vintage years
- Covers ACS5, ACS5 Data Profiles, ACS5 Subject Tables, ACS1, ACS1 Data Profiles, Population Estimates, Decennial Redistricting (P.L. 94-171), and Decennial DHC
- Accepts an optional keyword filter
- Dataset codes (e.g.,
acs/acs5) are the values to pass to other tools
census_search_variables
Search Census variables by keyword.
- Full-text search across label and concept fields with relevance scoring (exact concept match > label match > partial)
- Returns estimate (E suffix) and margin-of-error (M suffix) codes together so both can be requested in one query
- Configurable limit (default 20, max 100);
total_matchesindicates how many matched before the limit - Cache-backed: variables.json is fetched once per dataset+year with a configurable TTL (default 24h)
census_resolve_geography
Convert place names and addresses to Census FIPS identifiers.
- Named places (e.g., "King County, WA", "California") resolved via TIGERweb MapServer
- Street addresses resolved to tract level via Census Geocoder
- Auto-detects geography type from the name; accepts explicit
geography_typeoverride - Detects ambiguous names (multiple states) and returns candidates with recovery hints
- Returns
state_fips(→parent_fips) andfips_summary(→geography_fips) ready to pass to other tools
census_query_data
Query a Census dataset for one or more variables at a specific geography.
- Requires FIPS codes — use
census_resolve_geographyfirst for place names - Use
geography_fips: "*"to return all geographies at the level within the parent - Suppression codes (geography too small, data not collected, etc.) resolved to human-readable reasons
- Variable labels enriched from cache and surfaced alongside estimates
- Requires
CENSUS_API_KEY
census_compare_geographies
Rank and compare variables across multiple geographies.
- Fetches all geographies at a level (e.g., all WA counties) in one API call, then sorts and slices
- Optional
withinparameter to constrain to a parent FIPS; omit for national comparison - Optional
geographieslist to filter to specific FIPS values - Configurable sort variable, direction, and limit (default 50, max 500)
- Suppressed values sorted to end of results and labeled rather than passed through as negative sentinels
- Requires
CENSUS_API_KEY
Features
Built on @cyanheads/mcp-ts-core:
- Declarative tool definitions — single file per tool, framework handles registration and validation
- Unified error handling — handlers throw, framework catches, classifies, and formats with recovery hints
- Structured logging with optional OpenTelemetry tracing
- STDIO and Streamable HTTP transports
Census-specific:
- In-process variable cache with configurable TTL — variables.json fetched once per dataset+year, searched client-side
- Three-API backend: Census Data API for data queries, TIGERweb for named-place resolution, Census Geocoder for address-to-tract
- Automatic retry with backoff on all external API calls
- FIPS formatting helpers — zero-padded state, county, and tract codes ready to pass between tools
Agent-friendly output:
- Workflow-oriented tool surface —
fips_summaryandstate_fipsreturn values are ready to pass asgeography_fipsandparent_fipsto the next tool - Suppression codes decoded — Census negative sentinel values (e.g.,
-666666666) surfaced as human-readable reasons instead of raw numbers - Recovery hints on errors — ambiguous geography names include candidate lists; missing API key errors include registration URL
Getting started
API key: Register a free key at api.census.gov/data/key_signup.html. Variable search and geography resolution work without a key; data queries (
census_query_data,census_compare_geographies) require one.
Add the following to your MCP client configuration file:
{
"mcpServers": {
"census-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["census-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info",
"CENSUS_API_KEY": "your-census-api-key"
}
}
}
}
Or with npx (no Bun required):
{
"mcpServers": {
"census-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "census-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info",
"CENSUS_API_KEY": "your-census-api-key"
}
}
}
}
Or with Docker:
{
"mcpServers": {
"census-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"-e", "CENSUS_API_KEY=your-census-api-key",
"ghcr.io/cyanheads/census-mcp-server:latest"
]
}
}
}
For Streamable HTTP, set the transport and start the server:
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 CENSUS_API_KEY=... bun run start:http
# Server listens at http://localhost:3010/mcp
Prerequisites
- Bun v1.3.0 or higher (or Node.js v24+).
- A Census API key — register free at api.census.gov/data/key_signup.html. Required for
census_query_dataandcensus_compare_geographies; other tools work without it.
Installation
- Clone the repository:
git clone https://github.com/cyanheads/census-mcp-server.git
- Navigate into the directory:
cd census-mcp-server
- Install dependencies:
bun install
- Configure environment:
cp .env.example .env
# edit .env and set CENSUS_API_KEY
Configuration
| Variable | Description | Default |
|---|---|---|
CENSUS_API_KEY | Required for data queries. Register free at api.census.gov/data/key_signup.html. | — |
CENSUS_DEFAULT_YEAR | Default vintage year when no year is specified. | 2024 |
CENSUS_VARIABLE_CACHE_TTL_HOURS | Hours to cache variables.json per dataset+year in memory. | 24 |
MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
MCP_HTTP_PORT | Port for HTTP server. | 3010 |
MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none |
MCP_LOG_LEVEL | Log level (debug, info, notice, warning, error). | info |
OTEL_ENABLED | Enable OpenTelemetry instrumentation. | false |
See .env.example for the full list of optional overrides.
Running the server
Local development
# One-time build
bun run rebuild
# Run the built server
bun run start:stdio
# or
bun run start:http
Run checks and tests:
bun run devcheck # Lint, format, typecheck, security audit
bun run test # Vitest test suite
bun run lint:mcp # Validate MCP definitions against spec
Docker
docker build -t census-mcp-server .
docker run --rm -e CENSUS_API_KEY=your-key -p 3010:3010 census-mcp-server
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/census-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
| Path | Purpose |
|---|---|
src/index.ts | createApp() entry point — registers tools and initializes services. |
src/config/server-config.ts | Census-specific env var parsing and validation with Zod. |
src/mcp-server/tools/definitions/ | Tool definitions (*.tool.ts). |
src/services/census-api/ | Census Data API client — data queries, suppression code mapping, retry logic. |
src/services/geography/ | Geography resolution — TIGERweb named-place lookup and Census Geocoder address-to-tract. |
src/services/variable-cache/ | In-process variables.json cache with TTL and keyword search. |
tests/ | Vitest tests mirroring src/ structure. |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catchin tool logic - Use
ctx.logfor request-scoped logging,ctx.statefor tenant-scoped storage - Register new tools via the barrel in
src/mcp-server/tools/definitions/index.ts - Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues and pull requests are welcome. Run checks and tests before submitting:
bun run devcheck
bun run test
License
Apache-2.0 — see LICENSE for details.