Querido Diario MCP Server

Querido Diário MCP Server

Consulte diários oficiais municipais brasileiros diretamente pelo Claude, Cursor, Codex e outros clientes compatíveis com MCP.

Sem chave de API · Executa localmente · Somente leitura · Sem telemetria · Código aberto

🌎 English version: README.en.md

O Querido Diário MCP Server conecta agentes de IA à API pública do Querido Diário, permitindo consultar diários oficiais municipais brasileiros por meio de ferramentas estruturadas do Model Context Protocol (MCP).

Exemplo de uso:
"Encontre todas as menções a inteligência artificial nos diários oficiais de Porto Alegre em 2026."

O agente pode identificar o município correto, resolver seu código IBGE, consultar o índice de diários oficiais e devolver resultados estruturados sem que o usuário precise conhecer a API.

---

Por que este projeto existe?

O Querido Diário, mantido pela Open Knowledge Brasil, torna diários oficiais municipais brasileiros pesquisáveis por meio de uma plataforma de dados abertos e de uma API pública.

Este projeto adiciona uma interface nativa de MCP sobre essa API, permitindo que clientes e agentes de IA utilizem os dados diretamente como ferramentas.

Sem o MCP, um fluxo típico exigiria:

1. descobrir o município correto;
2. obter o código IBGE correspondente;
3. conhecer a API do Querido Diário;
4. montar os parâmetros de busca;
5. interpretar manualmente a resposta.

Com este servidor, um agente compatível com MCP pode executar esse fluxo de forma estruturada.

O servidor roda localmente como um subprocesso e realiza apenas requisições HTTPS de leitura para a API pública do Querido Diário.

---

O que dá para fazer?

Licitações, compras públicas e contratos

Pesquise empresas, processos licitatórios, contratos, termos de contratação e referências a compras governamentais.

"Encontre menções à ACME Ltda nos diários oficiais de Porto Alegre entre janeiro e julho de 2026."

Pessoas e organizações

Acompanhe menções a pessoas, empresas, associações, órgãos públicos e outras organizações.

"Pesquise João da Silva nos diários oficiais de Torres, RS."

Leis, decretos e atos administrativos

Pesquise legislação municipal, decretos, nomeações, exonerações, atos administrativos e mudanças regulatórias.

"Encontre publicações relacionadas à regulamentação de inteligência artificial."

Jornalismo de dados e pesquisa cívica

Use o Querido Diário como fonte estruturada em fluxos de pesquisa assistidos por IA.

"Busque contratos públicos relacionados a reconhecimento facial nos diários oficiais de Porto Alegre."

Agentes e automações

Combine a busca em diários oficiais com outros servidores MCP para criar fluxos maiores de investigação, classificação, acompanhamento e análise de informações públicas.

---

Início rápido

Requisitos:

• Python 3.12+
• uv, que fornece o comando uvx

Não é necessário clonar o repositório.

uvx querido-diario-mcp-server

Esse comando inicia o servidor MCP via stdio.

O servidor não possui interface interativa no terminal por design: ele foi feito para ser iniciado por um cliente MCP.

---

Conectando ao seu cliente de IA

Todos os clientes abaixo usam o mesmo comando:

uvx querido-diario-mcp-server

Claude Desktop / Claude Code

Adicione ao claude_desktop_config.json no Claude Desktop ou ao .mcp.json do projeto no Claude Code:

{
  "mcpServers": {
    "querido-diario": {
      "command": "uvx",
      "args": ["querido-diario-mcp-server"]
    }
  }
}

Cursor

Adicione ao .cursor/mcp.json do projeto ou às configurações globais de MCP do Cursor:

{
  "mcpServers": {
    "querido-diario": {
      "command": "uvx",
      "args": ["querido-diario-mcp-server"]
    }
  }
}

Codex CLI

Adicione ao arquivo ~/.codex/config.toml:

[mcp_servers.querido-diario]
command = "uvx"
args = ["querido-diario-mcp-server"]

Outros clientes MCP

Qualquer cliente compatível com servidores MCP locais via stdio pode utilizar:

• comando: uvx
• argumento: querido-diario-mcp-server

Consulte a documentação do seu cliente para o formato exato da configuração.

---

Ferramentas disponíveis

O servidor expõe propositalmente uma superfície pequena e somente leitura.

Sintaxe de busca

A ferramenta search_gazettes utiliza a sintaxe simple query string do OpenSearch usada pela API do Querido Diário.

Exemplos:

---

Exemplo completo

O usuário pergunta:

Encontre menções à ACME Ltda nos diários oficiais de Porto Alegre
entre janeiro e julho de 2026.

O cliente MCP pode executar:

1. search_cities(city_name="Porto Alegre")
   → territory_id: "4314902"

2. search_gazettes(
       query='"ACME Ltda"',
       territory_ids=["4314902"],
       published_since="2026-01-01",
       published_until="2026-07-31",
   )

O agente recebe os resultados de forma estruturada e pode então resumir, comparar, classificar ou combinar essas informações com outras ferramentas.

Outros exemplos de prompts:

Qual é o registro do município de Torres, RS, no Querido Diário?

Pesquise referências a compras públicas de inteligência artificial
nos diários oficiais de Porto Alegre.

Encontre publicações mencionando uma determinada empresa durante 2025.

Consulte o município correspondente ao código IBGE 3550308.

---

Demonstração

Ainda não há um vídeo, GIF ou captura de tela desta seção — de propósito, para não sugerir um comportamento que não foi validado de fato. Assim que houver uma demonstração real do servidor rodando dentro do Claude ou do Cursor, ela será adicionada aqui.

---

Como funciona

Cliente de IA
   │
   │ MCP / stdio
   ▼
querido-diario-mcp-server
   │
   │ requisições HTTPS tipadas
   ▼
API pública do Querido Diário

Estrutura do projeto:

src/querido_diario_mcp_server/
    __init__.py   # versão do pacote + ponto de entrada
    config.py     # configuração por variáveis de ambiente
    errors.py     # hierarquia de erros da integração
    models.py     # modelos Pydantic tipados
    client.py     # cliente HTTP assíncrono da API
    server.py     # camada MCP e definição das ferramentas

A implementação separa propositalmente a integração HTTP da camada MCP:

• client.py não depende do MCP;
• server.py concentra validação, ferramentas e comportamento de protocolo;
• um único httpx.AsyncClient é criado no ciclo de vida do servidor e reutilizado;
• erros da API são convertidos em mensagens MCP curtas e compreensíveis para o agente.

---

Local-first e somente leitura

O projeto foi desenhado para ser conservador em relação ao que um agente pode fazer.

• Executa somente requisições GET.
• Não possui operações de escrita.
• Não exige conta.
• Não exige chave de API.
• Não coleta telemetria.
• Não utiliza backend proprietário.
• Não utiliza proxy hospedado.
• O agente não pode fornecer uma URL arbitrária para o servidor buscar.
• URLs de diários retornadas pela API não são abertas automaticamente.
• Código IBGE, datas, paginação e ordenação são validados.
• Respostas de erro HTML da API não são repassadas integralmente ao agente.

Isso reduz a superfície de risco e evita transformar o servidor MCP em um mecanismo genérico de requisições externas ou SSRF.

Fora de escopo nesta fase

A versão atual não implementa:

• busca arbitrária de URLs;
• download automático de PDF ou texto integral;
• OCR;
• operações de escrita;
• banco de dados local;
• crawling;
• jobs em segundo plano;
• sumarização por LLM embutida;
• interface web.

O objetivo é manter uma camada MCP pequena, previsível e segura sobre a API pública existente.

---

Configuração

Para uso normal, nenhuma configuração adicional é necessária.

---

Instalação e distribuição

O pacote está publicado em:

• PyPI
• MCP Registry

Nome no PyPI:

querido-diario-mcp-server

Nome no MCP Registry:

io.github.lucaspmgomess/querido-diario-mcp-server

---

Desenvolvimento

Clone o repositório apenas se quiser contribuir ou trabalhar na implementação:

git clone https://github.com/lucaspmgomess/querido-diario-mcp-server.git
cd querido-diario-mcp-server
uv sync

Execute os mesmos checks usados pelo CI:

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest --cov

Para executar o servidor a partir do checkout local:

uv run querido-diario-mcp-server

Para inspecionar as ferramentas MCP interativamente:

uv run mcp dev src/querido_diario_mcp_server/server.py:mcp

---

Estratégia de testes

Testes do cliente HTTP

O client.py é testado com httpx.MockTransport, portanto a suíte automatizada não depende de internet nem de uma instância ativa do Querido Diário.

A cobertura inclui:

• requisições bem-sucedidas;
• busca de municípios;
• serialização de parâmetros;
• múltiplos territory_ids;
• períodos;
• paginação;
• ordenação;
• resultados vazios;
• erros 400/404/422;
• erros 5xx;
• respostas malformadas;
• timeouts;
• falhas de conexão.

Testes de integração MCP

Os testes de integração executam o servidor MCP real por meio do cliente in-process do SDK.

Eles verificam:

• descoberta das ferramentas;
• schemas de entrada;
• saída estruturada e tipada;
• falhas de validação;
• falhas da integração upstream;
• conversão de erros em mensagens MCP limpas, sem traceback Python bruto.

Smoke tests manuais

Há dois scripts de verificação manual contra produção:

uv run python scripts/smoke_test_api.py
uv run python scripts/smoke_test_mcp.py

Eles podem ser usados para validar a API real e o caminho completo MCP → cliente HTTP → API.

---

Relação com o Querido Diário

Este é um projeto comunitário e não oficial.

O Querido Diário é mantido pela Open Knowledge Brasil e sua comunidade.

Este repositório:

• não é um projeto oficial da Open Knowledge Brasil, salvo eventual adoção expressa pela organização;
• não é afiliado, endossado ou mantido pela Open Knowledge Brasil;
• não copia nem distribui a implementação do Querido Diário;
• apenas consulta a API pública do projeto.

Repositórios upstream relevantes:

• okfn-brasil/querido-diario — coleta/scrapers
• okfn-brasil/querido-diario-api — API pública
• okfn-brasil/querido-diario-deployment — configuração de deployment

A API de produção utilizada por padrão é:

https://api.queridodiario.org.br

Notas adicionais sobre o histórico dos endpoints estão em:

docs/upstream-api-history.md

---

Por que código aberto?

Existem integrações hospedadas que expõem dados do Querido Diário para clientes MCP.

Este projeto segue uma abordagem diferente:

• a implementação do servidor é pública;
• o servidor roda na máquina do próprio usuário;
• não há middleware hospedado;
• não há conta;
• não há chave de API;
• não há telemetria;
• a API pública do Querido Diário é acessada diretamente.

Assim, todo o caminho entre o agente e a fonte de dados pode ser inspecionado.

---

Feedback e uso real

Se você utilizar este projeto em pesquisa, civic tech, jornalismo de dados, análise de compras públicas ou em algum fluxo com agentes de IA, seu feedback é especialmente útil.

Exemplos de feedback que ajudam:

• uma busca difícil de expressar;
• um caso de município que não funcionou como esperado;
• dificuldade de configuração em algum cliente MCP;
• um filtro que faria diferença no uso real;
• comportamento inesperado da API upstream;
• um exemplo de como você está utilizando o servidor.

Abra uma issue descrevendo o caso de uso ou problema encontrado.

O objetivo é evoluir o projeto com base em uso real, mantendo o servidor pequeno, seguro e somente leitura.

---

Contribuindo

Issues e pull requests são bem-vindos.

Antes de abrir uma PR, execute:

uv run ruff check .
uv run ruff format --check .
uv run pyright
uv run pytest --cov

Mantenha novas ferramentas e comportamentos alinhados ao objetivo do projeto: oferecer a agentes compatíveis com MCP acesso seguro e estruturado à API pública do Querido Diário.

---

Licença

MIT