convez.ai
MCP ServerDados & AnalyticsIntermediário
cyanheads

Census MCP Server

cyanheads/census-mcp-server

Acesso integrado a dados demográficos e geográficos do Census Bureau dos EUA

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor MCP que consulta dados do Census Bureau dos EUA, incluindo variáveis demográficas, datasets históricos e geometrias geográficas. Fornece 7 ferramentas para buscar datasets, resolver geografias, pesquisar variáveis e comparar dados entre regiões via STDIO ou HTTP.

Instalação

$npx convez-ai cyanheads/census-mcp-server

1 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

Estrelas
3
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 3 dias
Versão
v0.8.0
Issues abertas
3
Contribuidores
1

Casos de uso

  • Pesquisa demográfica e análise de dados populacionais por região
  • Resolução de endereços e coordenadas para identificadores geográficos (FIPS)
  • Comparação de indicadores socioeconômicos entre estados, condados e municípios
  • Integração de dados censitários em dashboards e relatórios analíticos

Veredito

Servidor MCP maduro e bem documentado para quem precisa integrar dados demográficos americanos em workflows Claude. Cobertura completa do fluxo censitário (descoberta, busca, resolução geográfica, consulta) com suporte a múltiplos tipos de deploy, mas de utilidade restrita a contextos que trabalham com dados dos EUA.

README

A tradução para o português deste README ainda está na fila.

Version License Docker MCP SDK npm TypeScript Bun

Install in Claude Desktop Install in Cursor Install in VS Code

Framework

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:

ToolDescription
census_list_datasetsBrowse available Census Bureau datasets (ACS5, ACS1, Population Estimates, Decennial) with vintage years and dataset codes.
census_list_geographiesList the geography levels supported by a dataset and year, with parent requirements and example FIPS values.
census_search_variablesKeyword search across variable labels and concept groups. Returns estimate and margin-of-error codes together.
census_get_variableFetch full metadata for one or more variable codes — label, concept, predicate type, universe, MOE sibling.
census_resolve_geographyConvert place names (e.g., "King County, WA") or street addresses to Census FIPS identifiers via TIGERweb and Census Geocoder.
census_query_dataQuery a Census dataset for variables at a specific geography. Returns estimates with MOE, suppression codes resolved to readable reasons.
census_compare_geographiesRank 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_matches indicates 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_type override
  • Detects ambiguous names (multiple states) and returns candidates with recovery hints
  • Returns state_fips (→ parent_fips) and fips_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_geography first 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 within parameter to constrain to a parent FIPS; omit for national comparison
  • Optional geographies list 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_summary and state_fips return values are ready to pass as geography_fips and parent_fips to 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": ["@cyanheads/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", "@cyanheads/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

Installation

  1. Clone the repository:
git clone https://github.com/cyanheads/census-mcp-server.git
  1. Navigate into the directory:
cd census-mcp-server
  1. Install dependencies:
bun install
  1. Configure environment:
cp .env.example .env
# edit .env and set CENSUS_API_KEY

Configuration

VariableDescriptionDefault
CENSUS_API_KEYRequired for data queries. Register free at api.census.gov/data/key_signup.html.—
CENSUS_DEFAULT_YEARDefault vintage year when no year is specified.2024
CENSUS_VARIABLE_CACHE_TTL_HOURSHours to cache variables.json per dataset+year in memory.24
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for HTTP server.3010
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (debug, info, notice, warning, error).info
OTEL_ENABLEDEnable 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

PathPurpose
src/index.tscreateApp() entry point — registers tools and initializes services.
src/config/server-config.tsCensus-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/catch in tool logic
  • Use ctx.log for request-scoped logging, ctx.state for 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.

Ver o original no GitHub

Bom para

Relacionados