Skip to content
Back to search

mcp-portal-transparencia

MCP para orquestração automatizada de chamadas à API do Portal da Transparência do Governo Federal brasileiro

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dutradotdev--mcp-portal-transparencia/badge.svg)](/listings/dutradotdev--mcp-portal-transparencia)

HTML

<a href="/listings/dutradotdev--mcp-portal-transparencia"><img src="/api/listings/dutradotdev--mcp-portal-transparencia/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 266 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Portal da Transparência Brasil
  2. [![npm version](https://badge.fury.io/js/mcp-portal-transparencia-brasil.svg)](https://badge.fury.io/js/mcp-portal-transparencia-brasil)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  4. [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
  5. Um MCP Server que fornece acesso programático à API do Portal da Transparência do Governo Federal brasileiro através do protocolo MCP.
  6. **Este projeto apenas consome dados públicos disponibilizados pelo governo federal. Nenhum dado privado é armazenado ou exposto além do que já é acessível por qualquer cidadão via Portal da Transparência.**
  7. ## 📋 Sobre o Projeto
  8. Este projeto implementa um MCP Server que oferece acesso inteligente e estruturado a todos os endpoints disponíveis na API do Portal da Transparência (https://api.portaldatransparencia.gov.br/v3/api-docs). O sistema oferece:
  9. - **Integração MCP Completa** com suporte a Claude Desktop, Cursor e outras UIs compatíveis
  10. - **Geração Dinâmica de Ferramentas** a partir do Swagger/OpenAPI
  11. - **Autenticação Simplificada** com suporte a API Key via variáveis de ambiente
  12. - **Tratamento Robusto de Erros** com mensagens amigáveis em português
  13. - **Logs Estruturados** em JSON para monitoramento
  14. - **Suporte a NPX** para execução direta sem instalação
  15. ## 🚀 Funcionalidades
  16. ### ✅ Características Principais
  17. - 🔄 **Geração Dinâmica de Ferramentas MCP** a partir do Swagger V3
  18. - 🏗️ **Categorização Inteligente** de endpoints por área (servidores, contratos, etc.)
  19. - 🔐 **Sistema de Autenticação** via variável de ambiente `PORTAL_API_KEY`
  20. - 📊 **Logging Estruturado** com métricas detalhadas
  21. - 🔧 **Tratamento de Erros** com mensagens amigáveis em português
  22. - 📚 **Documentação Completa** e exemplos práticos
  23. ### 🎯 Endpoints Suportados
  24. O MCP Server fornece acesso a todos os endpoints do Portal da Transparência, incluindo:
  25. - **Servidores** - Dados do Poder Executivo Federal
  26. - **Viagens** - Consultas de viagens a serviço
  27. - **Licitações** - Informações sobre processos licitatórios
  28. - **Contratos** - Contratos do Poder Executivo Federal
  29. - **Despesas** - Gastos e empenhos governamentais
  30. - **Benefícios** - Programas sociais e beneficiários
  31. - **Sanções** - CNEP, CEIS e CEPIM
  32. - **Convênios** - Acordos e transferências
  33. - **Imóveis** - Imóveis funcionais
  34. - **Emendas** - Emendas parlamentares
  35. - **Notas Fiscais** - Documentos fiscais
  36. - **Coronavírus** - Dados específicos da pandemia
  37. ## 🛠️ Instalação
  38. ### Uso via npx (Recomendado para MCP Server)
  39. ```bash
  40. # Executar MCP Server diretamente (para Claude Desktop, Cursor, etc.)
  41. npx mcp-portal-transparencia-brasil
  42. # Ou instalar globalmente
  43. npm install -g mcp-portal-transparencia-brasil
  44. mcp-portal-transparencia-brasil
  45. ```
  46. ### Instalação local
  47. ```bash
  48. # Instalar via npm
  49. npm install mcp-portal-transparencia-brasil
  50. # Ou via yarn
  51. yarn add mcp-portal-transparencia-brasil
  52. ```
  53. ## ⚙️ Configuração
  54. ### Pré-requisitos
  55. - Node.js >= 16.0
  56. - Uma chave de API do Portal da Transparência (obrigatória)
  57. - Cliente MCP compatível (Claude Desktop, Cursor, etc.)
  58. ### Configuração para Cursor
  59. Adicione ao seu `.cursor/mcp.json`:
  60. ```json
  61. {
  62. "mcpServers": {
  63. "portal-transparencia": {
  64. "command": "npx",
  65. "args": ["mcp-portal-transparencia-brasil"],
  66. "env": {
  67. "PORTAL_API_KEY": "sua_api_key_aqui"
  68. }
  69. }
  70. }
  71. }
  72. ```
  73. ### Configuração para Claude Desktop
  74. Adicione ao seu `claude_desktop_config.json`:
  75. ```json
  76. {
  77. "mcpServers": {
  78. "portal-transparencia": {
  79. "command": "npx",
  80. "args": ["mcp-portal-transparencia-brasil"],
  81. "env": {
  82. "PORTAL_API_KEY": "sua_api_key_aqui"
  83. }
  84. }
  85. }
  86. }
  87. ```
  88. ## 🔍 Desenvolvimento com MCP Inspector
  89. O [MCP Inspector](https://github.com/modelcontextprotocol/inspector) é uma ferramenta oficial que permite testar e desenvolver visualmente todas as ferramentas MCP em uma interface web interativa. É essencial para o desenvolvimento e debugging do projeto.
  90. ### 🚀 Como Usar o Inspector
  91. 1. **Obtenha uma API Key**:
  92. - Acesse: https://api.portaldatransparencia.gov.br/api-de-dados/cadastrar-email
  93. - Guarde sua chave para usar nos próximos passos
  94. 2. **Execute o Inspector**:
  95. ```bash
  96. # Clone o repositório
  97. git clone https://github.com/dutradotdev/mcp-portal-transparencia
  98. cd mcp-portal-transparencia
  99. # Instale as dependências
  100. npm install
  101. # Execute o Inspector
  102. npm run inspector:direct
  103. ```
  104. 3. **Conecte ao Inspector**:
  105. - Clique no link que aparece no terminal: `Open inspector with token pre-filled`
  106. - No navegador, com o link aberto, procure `Add Environment Variable`
  107. - Adicione a Key `PORTAL_API_KEY` e Value gerado no portal da transparência
  108. - Aperte connect
  109. 4. **Recursos do Inspector para Desenvolvimento**:
  110. - 🔍 **Filtros**: Encontre ferramentas específicas rapidamente
  111. - 📝 **Documentação**: Veja detalhes de cada ferramenta
  112. - 🧪 **Teste**: Execute chamadas com diferentes parâmetros
  113. - 🐛 **Debug**: Visualize erros e respostas detalhadas
  114. - 💾 **Histórico**: Mantenha registro das chamadas realizadas
  115. ### 📝 Scripts NPM Disponíveis
  116. ```bash
  117. # Desenvolvimento
  118. npm run dev # Executar em modo desenvolvimento
  119. npm run build # Compilar TypeScript
  120. npm run test # Executar testes
  121. npm run lint # Verificar código
  122. npm run format # Formatar código
  123. # MCP Inspector
  124. npm run inspector # Executar com arquivo de configuração
  125. npm run inspector:direct # Executar diretamente
  126. ```
  127. ## 🧪 Testes
  128. ```bash
  129. # Testes unitários
  130. npm run test:unit
  131. # Testes de integração
  132. npm run test:integration
  133. # Cobertura de testes
  134. npm run test:coverage
  135. ```
  136. ## 📖 Uso via MCP (Recomendado)
  137. O MCP Server permite usar o Portal da Transparência diretamente através de ferramentas como Claude Desktop, Cursor, e outras interfaces compatíveis com MCP.
  138. ### Ferramentas Disponíveis
  139. Após configurar o MCP Server, você terá acesso a todas as ferramentas geradas automaticamente:
  140. - `portal_check_api_key` - Verificar se a API key está configurada
  141. - `portal_servidores_*` - Consultar dados de servidores públicos
  142. - `portal_viagens_*` - Consultar viagens a serviço
  143. - `portal_contratos_*` - Consultar contratos públicos
  144. - `portal_despesas_*` - Consultar despesas públicas
  145. - `portal_beneficios_*` - Consultar programas sociais
  146. - E muitas outras...
  147. ### Exemplos de Uso no Claude
  148. ```
  149. 🔍 Consultar servidores do Ministério da Fazenda
  150. 🎯 Buscar contratos acima de R$ 1 milhão
  151. 📊 Analisar despesas por órgão no último trimestre
  152. 🏛️ Verificar benefícios sociais por região
  153. ```
  154. ## 📖 Uso Programático (Biblioteca)
  155. Importante: Não testei esse projeto como biblioteca.
  156. O foco era o MCP.
  157. Use como biblioteca por sua conta e risco. (PRs são bem-vindos)
  158. ```typescript
  159. import { PortalTransparenciaClient } from 'mcp-portal-transparencia-brasil';
  160. // Inicializar o cliente
  161. const client = new PortalTransparenciaClient({
  162. apiKey: process.env.PORTAL_API_KEY,
  163. enableRateLimitAlerts: true,
  164. logLevel: 'info',
  165. });
  166. // Exemplo: Consultar viagens por período
  167. const viagens = await client.viagens.consultar({
  168. dataIdaDe: '01/01/2024',
  169. dataIdaAte: '31/01/2024',
  170. dataRetornoDe: '01/01/2024',
  171. dataRetornoAte: '31/01/2024',
  172. codigoOrgao: '26000',
  173. pagina: 1,
  174. });
  175. // Exemplo: Consultar servidores
  176. const servidores = await client.servidores.consultar({
  177. orgaoServidorLotacao: '26000',
  178. pagina: 1,
  179. });
  180. // Exemplo: Buscar licitações
  181. const licitacoes = await client.licitacoes.consultar({
  182. dataInicial: '01/01/2024',
  183. dataFinal: '31/01/2024',
  184. codigoOrgao: '26000',
  185. pagina: 1,
  186. });
  187. ```
  188. ## 🤝 Contribuindo
  189. 1. Faça um fork do projeto
  190. 2. Crie uma branch para sua feature (`git checkout -b feature/AmazingFeature`)
  191. 3. Commit suas mudanças (`git commit -m 'Add some AmazingFeature'`)
  192. 4. Push para a branch (`git push origin feature/AmazingFeature`)
  193. 5. Abra um Pull Request
  194. ## 📄 Licença
  195. Este projeto está licenciado sob a Licença MIT - veja o arquivo [LICENSE](LICENSE) para detalhes.
  196. ## 🔗 Links Úteis
  197. - [Portal da Transparência](https://portaldatransparencia.gov.br/)
  198. - [Documentação da API](https://api.portaldatransparencia.gov.br/swagger-ui/)
  199. - [Cadastro de API Key](https://api.portaldatransparencia.gov.br/api-de-dados/cadastrar-email)
  200. - [MCP Protocol](https://github.com/modelcontextprotocol/protocol)
  201. - [MCP Inspector](https://github.com/modelcontextprotocol/inspector)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.