convez.ai
MCP ServerDados & AnalyticsIntermediário
Taliawedged117

Census MCP Server

Taliawedged117/census-mcp-server

Consulte dados do Census Bureau diretamente no Claude com 7 ferramentas MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor 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-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
0
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 mês
Versão
—
Issues abertas
0
Contribuidores
2

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.

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": ["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

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