Skip to main content
Glama
gvc2000

MCP Câmara BR

by gvc2000
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

🏛️ MCP Câmara BR

Servidor MCP (Model Context Protocol) completo para a API de Dados Abertos da Câmara dos Deputados do Brasil.

Visão Geral

O mcp-camara-br é um servidor MCP que expõe todas as funcionalidades da API de Dados Abertos da Câmara dos Deputados através de tools tipadas, validadas e otimizadas para uso com Large Language Models (LLMs).

Características

  • ✅ Cobertura Completa - Mapeia os principais endpoints da API da Câmara

  • ✅ Validação Rigorosa - Inputs validados com Zod

  • ✅ Cache Inteligente - Sistema de cache em camadas com TTL diferenciado

  • ✅ Rate Limiting - Proteção contra sobrecarga da API

  • ✅ Circuit Breaker - Resiliência a falhas

  • ✅ Métricas - Observabilidade completa (Prometheus-ready)

  • ✅ Type-Safe - 100% TypeScript

  • ✅ Docker Ready - Containerizado e pronto para deploy

🚀 Início Rápido (5 minutos)

1. Instalar dependências

npm install

2. Compilar

npm run build

3. Configurar no Claude Desktop

Edite o arquivo de configuração:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

Linux:

~/.config/Claude/claude_desktop_config.json

Adicione a configuração:

macOS/Linux:

{ "mcpServers": { "camara-br": { "command": "node", "args": ["/caminho/completo/para/AgenteCidadaoMCP/dist/server.js"] } } }

Windows (use barras duplas

{ "mcpServers": { "camara-br": { "command": "node", "args": ["C:\\Users\\SeuUsuario\\AgenteCidadaoMCP\\dist\\server.js"] } } }

⚠️ Importante para Windows: Use barras duplas ( nos caminhos. Veja o Guia Windows para mais detalhes.

4. Reiniciar Claude Desktop

Feche e abra o Claude Desktop novamente.

Requisitos

  • Node.js >= 20.0.0

  • npm ou yarn

📖 Guias de Instalação Detalhados

Escolha o guia apropriado para seu sistema operacional:

Instalação Completa

# Clonar o repositório git clone https://github.com/gvc2000/AgenteCidadaoMCP.git cd AgenteCidadaoMCP # Instalar dependências npm install # Copiar arquivo de configuração cp .env.example .env # Build npm run build # Executar npm start

Uso com Docker

# Build da imagem docker-compose build # Executar docker-compose up -d # Ver logs docker-compose logs -f # Parar docker-compose down

Uso via HTTP (API REST)

O servidor também pode ser executado em modo HTTP, expondo uma API REST:

# Executar servidor HTTP npm run start:http # Ou em desenvolvimento com hot-reload npm run dev:http

Endpoints HTTP

  • GET / - Informações da API

  • GET /api/tools - Lista todas as ferramentas disponíveis

  • POST /api/tools/:toolName - Executa uma ferramenta

  • GET /health - Health check

  • GET /metrics - Métricas Prometheus

  • GET /metrics/json - Métricas em JSON

Exemplo de Uso HTTP

# Buscar deputados curl -X POST http://localhost:9090/api/tools/buscar_deputados \ -H "Content-Type: application/json" \ -d '{"uf":"SP","pagina":1,"itens":10}'

Configuração

Edite o arquivo .env para personalizar as configurações:

# API Configuration API_BASE_URL=https://dadosabertos.camara.leg.br/api/v2 # Cache CACHE_ENABLED=true CACHE_TTL_SECONDS=600 # Rate Limiting RATE_LIMIT_ENABLED=true RATE_LIMIT_PER_MINUTE=100 # Metrics METRICS_ENABLED=true METRICS_PORT=9090

🛠️ Tools Disponíveis (57 tools)

Tools de Ajuda

  • sugerir_ferramentas - Sugere quais tools usar para uma consulta

  • diagnosticar_consulta - Analisa objetivo e sugere fluxo completo de tools

Deputados (9)

  • buscar_deputados - Busca deputados por nome, UF, partido, etc.

  • detalhar_deputado - Informações detalhadas de um deputado

  • despesas_deputado - Despesas da cota parlamentar

  • discursos_deputado - Discursos proferidos

  • eventos_deputado - Eventos que participou

  • frentes_deputado - Frentes parlamentares das quais é membro

  • ocupacoes_deputado - Histórico de ocupações na Câmara

  • orgaos_deputado - Órgãos dos quais é membro

  • profissoes_deputado - Profissões declaradas

Proposições (7)

  • buscar_proposicoes - Busca proposições legislativas (PLs, PECs, MPs, etc.)

  • detalhar_proposicao - Informações detalhadas de uma proposição

  • autores_proposicao - Lista os autores de uma proposição

  • tramitacoes_proposicao - Histórico de tramitação

  • votacoes_proposicao - Votações da proposição

  • relacionadas_proposicao - Proposições relacionadas

  • temas_proposicao - Temas/assuntos da proposição

Votações (5)

  • buscar_votacoes - Busca votações por período ou proposição

  • detalhar_votacao - Resultado geral de uma votação

  • votos_votacao - Voto individual de cada deputado

  • orientacoes_votacao - Orientação dos partidos

  • ultimas_votacoes - Votações mais recentes

Eventos (6)

  • buscar_eventos - Busca reuniões e sessões por período

  • detalhar_evento - Informações de um evento

  • deputados_evento - Deputados presentes

  • pauta_evento - Pauta do evento

  • votacoes_evento - Votações realizadas

  • orgaos_evento - Órgãos participantes

Órgãos (5)

  • buscar_orgaos - Busca comissões e órgãos

  • detalhar_orgao - Informações de um órgão

  • membros_orgao - Composição atual

  • eventos_orgao - Eventos do órgão

  • votacoes_orgao - Votações do órgão

Partidos (4)

  • buscar_partidos - Lista partidos

  • detalhar_partido - Informações de um partido

  • membros_partido - Deputados do partido

  • lideres_partido - Liderança do partido

Frentes Parlamentares (3)

  • buscar_frentes - Busca frentes parlamentares

  • detalhar_frente - Informações de uma frente

  • membros_frente - Membros da frente

Blocos (2)

  • buscar_blocos - Busca blocos partidários

  • detalhar_bloco - Informações de um bloco

Legislaturas (3)

  • buscar_legislaturas - Lista legislaturas

  • detalhar_legislatura - Informações de uma legislatura

  • mesa_legislatura - Mesa Diretora

Referências (5)

  • situacoes_proposicao - Situações possíveis de proposições

  • tipos_proposicao - Tipos de proposições (PL, PEC, etc.)

  • tipos_orgao - Tipos de órgãos da Câmara

  • tipos_evento - Tipos de eventos

  • ufs - Unidades Federativas

Análises (6)

  • analise_presenca - Taxa de presença de deputados

  • ranking_proposicoes - Ranking de proposições

  • analise_despesas_partido - Despesas agregadas por partido

  • comparativo_votacoes - Compara votações

  • timeline_tramitacao - Timeline de tramitação

  • exportar_dados - Exporta dados para CSV/JSON

💬 Exemplos de Uso

Buscar Deputados de SP do PT

Liste deputados do estado de São Paulo no partido PT

Ou via JSON:

{ "tool": "buscar_deputados", "arguments": { "uf": "SP", "partido": "PT", "pagina": 1, "itens": 10 } }

Buscar Proposições sobre Educação

Busque projetos de lei sobre educação apresentados em 2024

Ou via JSON:

{ "tool": "buscar_proposicoes", "arguments": { "keywords": "educação", "ano": 2024, "pagina": 1, "itens": 20 } }

Frentes Parlamentares de um Deputado

Quais frentes parlamentares o deputado Guilherme Boulos participa?

Análise Completa de um Deputado

Me conte sobre a deputada Tabata Amaral: - Suas frentes parlamentares - Despesas de janeiro de 2024 - Discursos recentes sobre educação

Despesas de um Deputado

Mostre as despesas do deputado Guilherme Boulos em janeiro de 2024

Ou via JSON (usando ID):

{ "tool": "despesas_deputado", "arguments": { "id": 220000, "ano": 2024, "mes": 1 } }

Monitoramento

Métricas

O servidor expõe métricas no formato Prometheus:

# Métricas Prometheus curl http://localhost:9090/metrics # Métricas JSON curl http://localhost:9090/metrics/json # Health check curl http://localhost:9090/health

Logs

Os logs são estruturados em JSON (padrão) ou formato pretty para desenvolvimento:

# Ativar logs pretty LOG_FORMAT=pretty npm start

📁 Estrutura do Projeto

AgenteCidadaoMCP/ ├── src/ # Código-fonte do MCP Server │ ├── server.ts # Entry point │ ├── mcp.ts # MCP server setup │ ├── config.ts # Configurações │ │ │ ├── api/ # Cliente HTTP e comunicação │ │ ├── client.ts # Cliente HTTP com retry │ │ └── normalizers.ts # Normalização de dados │ │ │ ├── core/ # Sistemas core │ │ ├── cache.ts # Sistema de cache LRU │ │ ├── errors.ts # Classes de erro customizadas │ │ ├── logging.ts # Logs estruturados (Pino) │ │ ├── metrics.ts # Métricas Prometheus │ │ ├── rate-limiter.ts # Rate limiting (token bucket) │ │ ├── circuit-breaker.ts # Circuit breaker pattern │ │ ├── queue.ts # Fila de requisições │ │ └── schemas.ts # Schemas Zod compartilhados │ │ │ ├── tools/ # MCP Tools organizados por categoria │ │ ├── deputados/ # 10 tools sobre deputados │ │ ├── proposicoes/ # 8 tools sobre proposições │ │ ├── votacoes/ # 5 tools sobre votações │ │ ├── orgaos/ # 6 tools sobre órgãos │ │ ├── eventos/ # 7 tools sobre eventos │ │ ├── partidos/ # 5 tools sobre partidos │ │ ├── legislaturas/ # 4 tools sobre legislaturas │ │ ├── frentes/ # 4 tools sobre frentes │ │ ├── blocos/ # 3 tools sobre blocos │ │ ├── referencias/ # 6 tools de referência │ │ └── analises/ # 7 tools de análise e export │ │ │ └── utils/ # Utilitários │ ├── aggregators.ts # Agregação de dados │ ├── currency.ts # Formatação de moeda │ ├── date.ts # Utilitários de data │ └── sanitizers.ts # Sanitização de inputs │ ├── frontend/ # Interface Web │ ├── current/ # Versão atual (v4) │ │ ├── index.html # Interface principal │ │ ├── admin-agente-cidadao.html │ │ ├── demo-agente-cidadao.html │ │ └── login-agente-cidadao.html │ ├── archive/ # Versões anteriores │ └── README.md # Documentação do frontend │ ├── docs/ # Documentação organizada │ ├── guides/ # Guias de instalação e uso │ │ ├── GUIA_INSTALACAO_USO.md │ │ └── INICIO_RAPIDO.md │ ├── examples/ # Exemplos práticos │ │ ├── EXEMPLOS_PRATICOS.md │ │ └── EXEMPLOS_TESTES.md │ ├── testing/ # Planos e relatórios de testes │ ├── process/ # Artefatos de processo │ ├── specs/ # Especificações técnicas │ │ └── mcp-camara-br-especificacao-completa.md │ └── README.md # Índice da documentação │ ├── scripts/ # Scripts utilitários │ └── healthcheck.sh # Health check para deploy │ ├── .github/ # GitHub Actions │ └── workflows/ │ ├── ci.yml # CI/CD pipeline │ └── release.yml # Release automation │ ├── dist/ # Código compilado (gerado) │ ├── .env.example # Template de variáveis de ambiente ├── .dockerignore # Arquivos ignorados no Docker build ├── .npmignore # Arquivos ignorados no npm publish ├── Dockerfile # Multi-stage Docker build ├── docker-compose.yml # Docker Compose config ├── package.json # Configuração npm ├── tsconfig.json # Configuração TypeScript │ ├── README.md # Este arquivo ├── CONTRIBUTING.md # Guia de contribuição ├── CLAUDE.md # Guia para assistentes de IA └── LICENSE # Licença MIT

Desenvolvimento

# Modo desenvolvimento com watch npm run dev # Testes npm test # Cobertura de testes npm run test:coverage # Linting npm run lint # Formatação npm run format # Type checking npm run type-check

⚡ Performance

O servidor implementa várias otimizações:

  • Cache em Camadas: Diferentes TTLs por tipo de dado

  • Rate Limiting: Token bucket algorithm

  • Circuit Breaker: Previne cascata de falhas

  • Request Queue: Controla concorrência

  • Retry Logic: Exponential backoff com jitter

🔄 CI/CD

O projeto possui workflows automatizados do GitHub Actions:

CI (Integração Contínua)

  • ✅ Type checking (TypeScript)

  • ✅ Linting (ESLint)

  • ✅ Formatação (Prettier)

  • ✅ Testes automatizados

  • ✅ Build em Node.js 20.x e 21.x

  • ✅ Build Docker

Release (Publicação)

  • 🚀 Criação automática de releases no GitHub

  • 🚀 Build de imagens Docker em tags

  • 📦 Preparado para publicação no npm (requer configuração)

Configuração: Os workflows estão em .github/workflows/:

  • ci.yml - Executado em push/PR para main/develop

  • release.yml - Executado ao criar tags (v*)

📚 Documentação Completa

Guias

Exemplos e Testes

Especificações

Integrações

Para Desenvolvedores

Índice Completo

🤝 Contribuindo

Contribuições são muito bem-vindas! Este projeto segue boas práticas de desenvolvimento e possui diretrizes claras para contribuidores.

Antes de contribuir, leia:

  • CONTRIBUTING.md - Guia completo de contribuição com padrões de código, workflow e boas práticas

Resumo rápido:

  1. Fork o projeto

  2. Crie uma branch para sua feature (git checkout -b feature/MinhaFeature)

  3. Siga os padrões de código (TypeScript strict, ESLint, Prettier)

  4. Escreva testes para novas funcionalidades

  5. Commit usando Conventional Commits (feat:, fix:, etc.)

  6. Push para a branch (git push origin feature/MinhaFeature)

  7. Abra um Pull Request com descrição detalhada

Scripts úteis para desenvolvimento:

npm run validate # Executa type-check + lint + format-check + tests npm run lint:fix # Corrige problemas de lint automaticamente npm run format # Formata o código com Prettier

Licença

MIT License - veja o arquivo LICENSE para detalhes.

🔗 Links

Suporte

Para reportar bugs ou solicitar features, abra uma issue.

Desenvolvido com ❤️ para democratização de dados públicos

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Resources

Tools

View all tools

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/gvc2000/AgenteCidadaoMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server