CongressMCP

CongressMCP

Dados legislativos dos EUA em tempo real para qualquer cliente MCP — Claude Code, ChatGPT, Copilot, Codex, Cursor, OpenCode, Gemini CLI, Grok Build e outros.

Projetos de lei, texto completo de projetos, votações, membros, comissões, audiências, nomeações e o Congressional Record — consultados em linguagem natural por meio do Model Context Protocol. Executa localmente na sua máquina usando as APIs gratuitas Congress.gov e GovInfo. Sem conta, sem serviço hospedado, sem telemetria.

Início Rápido

1. Obtenha uma chave gratuita da API Congress.gov

Cadastre-se em api.congress.gov/sign-up — leva 30 segundos. A mesma chave também funciona para GovInfo (texto completo de projetos).

2. Instale o uv

O CongressMCP é publicado no PyPI e iniciado com uvx, que acompanha o uv:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

(brew install uv, winget install astral-sh.uv e pipx install uv também funcionam.) Prefere pip? O pip install congressmcp fornece um comando congressmcp que você pode usar no lugar de uvx congressmcp abaixo.

3. Conecte seu cliente

Todo cliente precisa dos mesmos três dados: comando uvx, argumentos ["congressmcp"], variáveis de ambiente CONGRESS_API_KEY. Os clientes estão listados aproximadamente pela quantidade de desenvolvedores profissionais que os usam hoje (pesquisa JetBrains Developer Ecosystem, meados de 2026, depois pesquisa de ferramentas do Pragmatic Engineer de 2026), então o que você procura provavelmente está perto do topo:

Qualquer coisa não listada que fale MCP via stdio funcionará com os mesmos três valores.

# just for you
claude mcp add congressmcp --env CONGRESS_API_KEY=your-api-key-here -- uvx congressmcp

# shared with your team via .mcp.json in the repo root
claude mcp add --scope project congressmcp --env CONGRESS_API_KEY='${CONGRESS_API_KEY}' -- uvx congressmcp

{
  "mcpServers": {
    "congressmcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["congressmcp"],
      "env": { "CONGRESS_API_KEY": "${CONGRESS_API_KEY}" }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "congress-api-key",
      "description": "Congress.gov API key",
      "password": true
    }
  ],
  "servers": {
    "congressmcp": {
      "type": "stdio",
      "command": "uvx",
      "args": ["congressmcp"],
      "env": { "CONGRESS_API_KEY": "${input:congress-api-key}" }
    }
  }
}

codex mcp add congressmcp --env CONGRESS_API_KEY=your-api-key-here -- uvx congressmcp

[mcp_servers.congressmcp]
command = "uvx"
args = ["congressmcp"]
env_vars = ["CONGRESS_API_KEY"]   # forward from your shell — nothing secret in the file

{
  "mcpServers": {
    "congressmcp": {
      "command": "uvx",
      "args": ["congressmcp"],
      "env": { "CONGRESS_API_KEY": "${env:CONGRESS_API_KEY}" }
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "congressmcp": {
      "type": "local",
      "command": ["uvx", "congressmcp"],
      "environment": { "CONGRESS_API_KEY": "your-api-key-here" },
      "enabled": true
    }
  }
}

gemini mcp add -s user -e CONGRESS_API_KEY=your-api-key-here congressmcp uvx congressmcp

{
  "mcpServers": {
    "congressmcp": {
      "command": "uvx",
      "args": ["congressmcp"],
      "env": { "CONGRESS_API_KEY": "$CONGRESS_API_KEY" }
    }
  }
}

{
  "mcpServers": {
    "congressmcp": {
      "command": "uvx",
      "args": ["congressmcp"],
      "env": { "CONGRESS_API_KEY": "your-api-key-here" }
    }
  }
}

{
  "mcpServers": {
    "congressmcp": {
      "command": "uvx",
      "args": ["congressmcp"],
      "env": { "CONGRESS_API_KEY": "${env:CONGRESS_API_KEY}" }
    }
  }
}

{
  "context_servers": {
    "congressmcp": {
      "command": "uvx",
      "args": ["congressmcp"],
      "env": { "CONGRESS_API_KEY": "your-api-key-here" }
    }
  }
}

{
  "mcpServers": {
    "congressmcp": {
      "command": "uvx",
      "args": ["congressmcp"],
      "env": { "CONGRESS_API_KEY": "your-api-key-here" },
      "disabled": false,
      "autoApprove": []
    }
  }
}

extensions:
  congressmcp:
    name: congressmcp
    type: stdio
    cmd: uvx
    args: [congressmcp]
    envs: { "CONGRESS_API_KEY": "your-api-key-here" }
    enabled: true
    timeout: 300

grok mcp add congressmcp -- uvx congressmcp      # add --scope project for .grok/config.toml

[mcp_servers.congressmcp]
command = "uvx"
args = ["congressmcp"]
env = { CONGRESS_API_KEY = "${CONGRESS_API_KEY}" }

mcp_servers:
  congressmcp:
    command: "uvx"
    args: ["congressmcp"]
    env:
      CONGRESS_API_KEY: "${CONGRESS_API_KEY}"   # or a literal key
    enabled: true

openclaw mcp add congressmcp --command uvx --arg congressmcp --env CONGRESS_API_KEY=your-api-key-here

{
  mcp: {
    servers: {
      congressmcp: {
        command: "uvx",
        args: ["congressmcp"],
        env: { CONGRESS_API_KEY: "your-api-key-here" },
      },
    },
  },
}

mcpServers:
  - name: congressmcp
    type: stdio
    command: uvx
    args:
      - congressmcp
    env:
      CONGRESS_API_KEY: ${{ secrets.CONGRESS_API_KEY }}

4. Comece a fazer perguntas

"Encontre projetos de lei recentes sobre mudanças climáticas no 119º Congresso" "Onde no NDAA do FY2026 está o financiamento do quebra-gelo da Guarda Costeira?" "Como os senadores da Califórnia votaram no projeto de lei de defesa mais recente?" "Quem são os membros do Comitê Judiciário do Senado?" "Qual é a ação mais recente sobre o H.R. 1234?"

Modo remoto / HTTP

Para clientes que se conectam por URL (conectores do ChatGPT, Claude.ai, Open WebUI, ou vários usuários compartilhando uma instalação), execute o servidor via Streamable HTTP:

CONGRESS_API_KEY=your-key congressmcp --transport streamable-http --host 0.0.0.0 --port 8000
# MCP endpoint: http://<host>:8000/mcp

O CongressMCP não possui autenticação integrada. O servidor foi projetado para rodar na sua própria máquina. Se você o expor além do localhost, coloque-o atrás de algo que autentique — um proxy reverso com política de acesso, um túnel HTTPS com lista de permissões, ou uma VPN — e lembre-se de que qualquer pessoa que conseguir acessá-lo estará gastando sua cota do Congress.gov. ChatGPT e Claude.ai também exigem HTTPS em um hostname publicamente resolvível.

Ferramentas

7 conjuntos de ferramentas, 90+ operações cobrindo a API do Congress.gov, além de recuperação de texto completo de projetos de lei do GovInfo:

search_committees e search_summaries aceitam um argumento keywords opcional — omitir para navegar/listar (comitês também podem ser filtrados por chamber/committee_type).

Pesquisa de texto completo de projetos de lei

O que mudou: em vez de fazer proxy das respostas da API, o CongressMCP busca o XML DTD completo do projeto de lei do GovInfo, analisa localmente, constrói um índice SQLite FTS5 por versão do projeto de lei, e retorna seções direcionadas e endereçáveis em vez de XML bruto de vários megabytes ou páginas inteiras renderizadas. Os índices são persistidos em disco e reutilizados entre chamadas e reinicializações.

Nenhuma nova chave de API é necessária. GovInfo e Congress.gov estão ambos atrás de api.data.gov, então o CongressMCP reutiliza sua CONGRESS_API_KEY existente para ambos; defina GOVINFO_API_KEY apenas se quiser uma chave GovInfo separada. (As pessoas assumem que uma segunda chave é necessária. Não é.)

Onde os dados ficam. Um arquivo SQLite por versão de projeto de lei (<package_id>.v<N>.db, ex.: BILLS-119s1071enr.v1.db) em packages/ na raiz do cache, além de um pequeno índice manifest.db. A raiz do cache é CONGRESSMCP_CACHE_DIR se definido, caso contrário o padrão da plataforma:

Quanto espaço em disco. Limitado a 500 MB por padrão (CONGRESSMCP_CACHE_MAX_BYTES, bytes), aplicado por evicção de menos usados recentemente após cada gravação de índice. Um projeto de lei promulgado em escala NDAA (S.1071/119, 1.448 unidades indexadas) constrói um índice de 11 MB; a maioria dos projetos de lei é muito menor. Inspecione ou esvazie o cache pela linha de comando — deliberadamente não é uma ferramenta MCP:

congressmcp cache info          # path, cap, total bytes, one line per package
congressmcp cache clear --yes   # remove every package file and the manifest

Excluir o diretório de cache manualmente também é seguro a qualquer momento; os arquivos são um cache, não um armazenamento.

Latência da primeira chamada — medida, não estimada. Frio (nada em cache) em S.1071/119: 4,1–6,8 s de ponta a ponta entre execuções, dos quais a resolução de versão do congress.gov + o resumo do pacote GovInfo levaram 3,0–3,4 s, o download do XML 1,1–2,3 s, a análise 0,75 s, e a construção do FTS5 0,31 s — as etapas de rede são a parte lenta e variável, e são a parte que o cache remove. Quente (índice e resolução de versão em cache): 30–60 ms, sem rede. Cada resposta carrega um bloco timing (resolve_ms, download_ms, parse_ms, index_ms, search_ms, total_ms; uma etapa é null quando não foi executada) e um bloco cache (index_hit, version_hit), para que você possa ver qual caso obteve. Implicação de timeout do cliente: defina o timeout por chamada do seu cliente MCP para pelo menos 30 s; uma chamada fria em escala NDAA sob uma rede lenta pode exceder o padrão de 10 s e o trabalho parcial não é perdido — a próxima chamada será quente.

Comportamento offline. Uma versão que você buscou explicitamente (version="enr") é totalmente consultável offline enquanto permanecer no cache; versões explicitamente em cache são re-verificadas contra o lastModified do GovInfo apenas a cada CONGRESSMCP_REVALIDATE_DAYS (30) e reconstruídas se o pacote foi reemitido. Com version omitido, a resposta de "versão mais recente" é armazenada em cache por CONGRESSMCP_VERSION_TTL (86400 s = 1 dia; version_resolution: "cached"); após o TTL, é re-resolvida, e se a rede estiver indisponível, a última resposta é servida melhor esforço e rotulada version_resolution: "cached_offline" com o timestamp de resolução e uma nota de que uma versão mais recente pode existir. Se nada estiver em cache e a rede estiver fora, você recebe version_resolution_unavailable, listando as versões desse projeto de lei que estão em cache para que você possa fixar uma.

Egresso de rede. Exatamente dois hosts: api.congress.gov (metadados de projeto de lei e versão de texto) e api.govinfo.gov (conteúdo do projeto de lei). Ambos limitados independentemente por api.data.gov (20.000/h e 36.000/h), então a indexação não pode esgotar as outras ferramentas.

Definir CONGRESSMCP_CACHE_ENABLED=false desativa tudo isso: cada chamada re-baixa, re-analisa e re-indexa o documento completo em memória — latência em escala NDAA, toda vez. Existe para diagnóstico, não para uso normal.

A resposta de pesquisa distingue correspondências em segmentos operative, quoted e header. Se quoted aparecer em match_contexts, a correspondência pode incluir linguagem que o projeto de lei está removendo, mesmo quando operative também aparece; recupere a seção antes de tirar conclusões sobre linguagem de substituição e inserção.

Cada correspondência também carrega matched_queries — o subconjunto de suas consultas que a produziu. Leia antes de raciocinar sobre o comportamento de recuperação: em uma chamada multi-consulta, atribui cada correspondência à sua consulta de origem, então um resultado inesperado é explicado pelo campo, não por adivinhar internals do tokenizador.

amends resolve apenas citações do Código dos EUA (a forma longa Section {sec} of title {title}, United States Code e a forma abreviada {title} U.S.C. {sec} quando um verbo de emenda segue). Não resolve Atos nomeados, incluindo o Internal Revenue Code citado por número de seção simples — então a maioria das unidades fiscais do Título VII reporta is_amendatory: true com amends: []. Use is_amendatory e match_contexts para identificar texto de emenda; amends é uma conveniência, não uma garantia de completude.

Executando a partir do código-fonte

git clone https://github.com/amurshak/congressMCP
cd congressMCP
pip install -e .

# stdio (default — for MCP clients)
CONGRESS_API_KEY=your-key congressmcp

# HTTP (for self-hosting / remote access)
CONGRESS_API_KEY=your-key congressmcp --transport streamable-http --port 8000

Aponte um cliente para um checkout do código-fonte usando "command": "congressmcp" (com o venv ativado ou seu bin/ no PATH) ou "command": "/path/to/venv/bin/congressmcp" no lugar de uvx.

Configuração

CLI de cache (o cache é administrado pela linha de comando, nunca via ferramenta MCP):

congressmcp cache info          # exit 0
congressmcp cache clear --yes   # exit 0; without --yes in a non-interactive shell it refuses with exit 1

Solução de problemas

• "command not found: uvx" em um cliente GUI (Claude Desktop, Zed, LM Studio, JetBrains): use o caminho absoluto de which uvx (macOS/Linux) ou where uvx (Windows) como o command.
• Windows: se um cliente não puder iniciar uvx diretamente, use "command": "cmd", "args": ["/c", "uvx", "congressmcp"].
• Primeira inicialização é lenta: uvx baixa e armazena o pacote em cache na primeira execução; inicializações subsequentes são rápidas. Fixe uma versão com uvx congressmcp@2.2.0 se quiser reprodutibilidade.
• 401 / 403 da API: a chave está ausente ou errada. Confirme que funciona com curl "https://api.congress.gov/v3/bill?api_key=YOUR_KEY&limit=1".
• Ferramentas ausentes no cliente: a maioria dos clientes precisa de reinicialização ou recarga explícita do MCP após editar a configuração.

Contribuindo

Veja CONTRIBUTING.md para o processo completo: fork, branch, estilo de código, convenções de commit e como enviar um pull request.

Licença

Licença de Uso Sustentável

Construído para transparência governamental e dados cívicos acessíveis.