ZIP-County Crosswalk MCP

Servidor MCP de Crosswalk ZIP↔Condado

Um servidor Model Context Protocol (MCP) que permite ao Claude consultar relações ZIP-para-condado e condado-para-ZIP, usando a API oficial de Crosswalk de CEPs do USPS da HUD — incluindo filtragem por sobreposição de endereços residenciais, já que os CEPs rotineiramente cruzam as linhas dos condados.

Arquitetura

flowchart LR
    Claude -->|MCP tool call| Server[zip-county-mcp server]
    Server -->|overlap ratios| HUD[HUD USPS Crosswalk API]
    Server -->|county names| BQ[(BigQuery:\ngeo_us_boundaries)]

Por que isso existe

CEPs e condados não se alinham perfeitamente — um único CEP pode se espalhar por vários condados, cada um com uma parcela diferente dos endereços residenciais daquele CEP. A maioria das consultas simples de ZIP↔condado ignora isso e apenas retorna uma resposta, que muitas vezes está errada para o condado que detém uma pequena fatia do CEP. Este servidor expõe os dados reais de proporção de sobreposição da HUD para que um chamador possa filtrar fatias insignificantes via um limite min_overlap_pct, e obter nomes precisos de condados por meio de um conjunto de dados público do BigQuery.

Exemplo: o CEP 77494 (Katy, TX) está, na verdade, dividido entre três condados — Fort Bend (83,4%), Harris (16,5%) e Waller (0,17%). Um chamador que só queira condados que realmente compõem aquele CEP pode definir min_overlap_pct=5 e receber apenas Fort Bend e Harris.

Como a sobreposição é realmente medida

A porcentagem de sobreposição vem diretamente do campo res_ratio da HUD, e vale a pena ser preciso sobre o que esse campo significa (verificado em documentação oficial da API da HUD, não presumido):

• É uma proporção de endereços residenciais, não de população/contagem de pessoas. Um endereço de uma pessoa e um endereço de cinco pessoas contam ambos como "1" para a proporção — endereços são um proxy razoável para população, mas não a mesma medição.
• O denominador muda com a direção da consulta. Para zip_to_county (HUD type=2), res_ratio é endereços-neste-condado ÷ endereços-no-CEP-inteiro. Para zips_in_county (HUD type=7, a consulta reversa), é endereços-neste-CEP ÷ endereços-no-condado-inteiro. Mesmo nome de campo, denominador diferente — é por isso que um condado populoso como Harris mostra dezenas de CEPs com apenas 1-3% cada, enquanto um único CEP pode mostrar um condado com 80%+: as duas porcentagens não estão medindo contra o mesmo total.

Status

Todas as três ferramentas estão implementadas, testadas (7 testes passando, pytest) e verificadas de ponta a ponta contra dados ao vivo da HUD + BigQuery e uma conexão real com o Claude Desktop.

Configuração

1. Obtenha uma conta gratuita na API da HUD e um token Bearer em huduser.gov.
2. Confirme que você tem acesso ao BigQuery para bigquery-public-data.geo_us_boundaries (por exemplo, via gcloud auth application-default login).
3. Copie .env.example para .env e preencha HUD_API_TOKEN e seu projeto do Google Cloud.
4. Crie um virtualenv com Python 3.10+ (o pacote mcp exige isso — no macOS, o python3 do sistema costuma ser mais antigo, então verifique python3 --version primeiro) e instale as dependências:

   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   

5. Execute: .venv/bin/python3 server.py

Conectando ao Claude Desktop

Adicione uma entrada ao seu claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

"mcpServers": {
  "zip-county-mcp": {
    "command": "/absolute/path/to/zip-county-mcp/.venv/bin/python3",
    "args": ["/absolute/path/to/zip-county-mcp/server.py"]
  }
}

Saia completamente e reabra o Claude Desktop (os servidores MCP só carregam na inicialização) e então tente uma das perguntas abaixo.

Exemplo de uso

Depois de conectado, basta perguntar ao Claude em português simples — ele escolhe a ferramenta e os argumentos certos por conta própria. Alguns exemplos reais (verificados com dados ao vivo):

Consultar um único CEP:

"Em que condado fica o CEP 77002?"

O Claude chama zip_to_county("77002") → o CEP 77002 (Houston, TX) está inteiramente no Condado de Harris, TX (FIPS 48201) — 100% de sobreposição.

Um CEP que cruza linhas de condados:

"Com quais condados o CEP 77494 se sobrepõe, e em quanto?"

O Claude chama zip_to_county("77494") → três condados: Fort Bend (83,4%), Harris (16,5%), Waller (0,17%). Faça uma pergunta de acompanhamento como "apenas os com pelo menos 5%" e ele re-chama com min_overlap_pct=5, descartando a fatia insignificante de Waller.

Consulta reversa — CEPs dentro de um condado:

"Quais CEPs estão no Condado de Harris, Texas?" (ou forneça o código FIPS, 48201, diretamente)

O Claude chama zips_in_county("48201") → uma lista de cada CEP com uma parcela significativa dos endereços residenciais do Condado de Harris, ordenada por sobreposição.

Uma lista de CEPs de uma vez:

"Em quais condados estão os CEPs 77002, 77494 e 10001?"

O Claude chama batch_zip_to_county(["77002", "77494", "10001"]) → um resultado por CEP em uma única resposta, sem consultar o BigQuery uma vez por CEP nos bastidores.

Ferramentas (escopo v1)

• zip_to_county(zip_code, min_overlap_pct=0) — condado(s) para um CEP, com % de sobreposição
• zips_in_county(county_fips, min_overlap_pct=0) — CEPs em um condado, com % de sobreposição
• batch_zip_to_county(zip_codes, min_overlap_pct=0) — igual ao acima, vários CEPs de uma vez

Fora do escopo para v1: consultas em nível de setor censitário, crosswalks de CBSA/distrito congressional, camada de cache, outros tipos de geografia.

Testes

.venv/bin/pip install -r requirements.txt
.venv/bin/python3 -m pytest tests/ -v

Os testes simulam as respostas da API da HUD (httpx.MockTransport) e a consulta de nomes do BigQuery, então eles rodam em cerca de um segundo sem exigir token ao vivo ou acesso ao BigQuery.