Querido Diário MCP Server
Unofficial, read-only MCP server for the public Querido Diário API (Brazilian municipal gazettes)
Open source Open in the app JSON README (API)
About
Unofficial, read-only MCP server for the public Querido Diário API (Brazilian municipal gazettes)
Details
- Kind
- MCP servers
- Topic
- Government & public data
- Publisher
- lucaspmgomess
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.0
- Last push
- 2026-09-02T01:28:28Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-31 21:00:07
- Updated
- 2026-08-31 21:00:07
- Origin id
io.github.lucaspmgomess/querido-diario-mcp-server
README
# Querido Diário MCP Server
<!-- mcp-name: io.github.lucaspmgomess/querido-diario-mcp-server -->
**Consulte diários oficiais municipais brasileiros diretamente pelo Claude, Cursor, Codex e outros clientes compatíveis com MCP.**
[](https://pypi.org/project/querido-diario-mcp-server/)
[](https://pypi.org/project/querido-diario-mcp-server/)
[](https://github.com/lucaspmgomess/querido-diario-mcp-server/actions/workflows/ci.yml)
[](https://registry.modelcontextprotocol.io/?q=io.github.lucaspmgomess%2Fquerido-diario-mcp-server)
[](./LICENSE)
**Sem chave de API · Executa localmente · Somente leitura · Sem telemetria · Código aberto**
> 🌎 **English version:** [README.en.md](./README.en.md)
O **Querido Diário MCP Server** conecta agentes de IA à API pública do [Querido Diário](https://queridodiario.org.br), 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](https://queridodiario.org.br), mantido pela [Open Knowledge Brasil](https://ok.org.br/), 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`](https://docs.astral.sh/uv/), que fornece o comando `uvx`
Não é necessário clonar o repositório.
```bash
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:
```bash
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:
```json
{
"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:
```json
{
"mcpServers": {
"querido-diario": {
"command": "uvx",
"args": ["querido-diario-mcp-server"]
}
}
}
```
### Codex CLI
Adicione ao arquivo `~/.codex/config.toml`:
```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.
| Ferramenta | Finalidade |
|---|---|
| `search_cities` | Busca municípios brasileiros por nome parcial e resolve o código IBGE de 7 dígitos. Permite filtro opcional por estado. |
| `get_city` | Consulta os detalhes de um município usando seu código IBGE exato de 7 dígitos. |
| `search_gazettes` | Realiza busca textual em diários oficiais indexados, com filtros por município, período, paginação e ordenação. |
### Sintaxe de busca
A ferramenta `search_gazettes` utiliza a sintaxe **simple query string** do OpenSearch usada pela API do Querido Diário.
Exemplos:
| Consulta | Significado |
|---|---|
| `inteligência artificial` | Encontra qualquer um dos termos |
| `+inteligência +artificial` | Exige os dois termos |
| `-cancelado` | Exclui um termo |
| `"João da Silva"` | Busca uma expressão exata |
---
## Exemplo completo
O usuário pergunta:
```text
Encontre menções à ACME Ltda nos diários oficiais de Porto Alegre
entre janeiro e julho de 2026.
```
O cliente MCP pode executar:
```text
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:
```text
Qual é o registro do município de Torres, RS, no Querido Diário?
```
```text
Pesquise referências a compras públicas de inteligência artificial
nos diários oficiais de Porto Alegre.
```
```text
Encontre publicações mencionando uma determinada empresa durante 2025.
```
```text
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
```text
Cliente de IA
│
│ MCP / stdio
▼
querido-diario-mcp-server
│
│ requisições HTTPS tipadas
▼
API pública do Querido Diário
```
Estrutura do projeto:
```text
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
| Variável | Padrão | Finalidade |
|---|---|---|
| `QD_API_BASE_URL` | `https://api.queridodiario.org.br` | URL base da API do Querido Diário. Pode ser sobrescrita para ambientes locais ou de staging. |
Para uso normal, nenhuma configuração adicional é necessária.
---
## Instalação e distribuição
O pacote está publicado em:
- [PyPI](https://pypi.org/project/querido-diario-mcp-server/)
- [MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.lucaspmgomess%2Fquerido-diario-mcp-server)
Nome no PyPI:
```text
querido-diario-mcp-server
```
Nome no MCP Registry:
```text
io.github.lucaspmgomess/querido-diario-mcp-server
```
---
## Desenvolvimento
Clone o repositório apenas se quiser contribuir ou trabalhar na implementação:
```bash
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:
```bash
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:
```bash
uv run querido-diario-mcp-server
```
Para inspecionar as ferramentas MCP interativamente:
```bash
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:
```bash
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](https://queridodiario.org.br) é mantido pela [Open Knowledge Brasil](https://ok.org.br/) 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](https://github.com/okfn-brasil/querido-diario) — coleta/scrapers
- [okfn-brasil/querido-diario-api](https://github.com/okfn-brasil/querido-diario-api) — API pública
- [okfn-brasil/querido-diario-deployment](https://github.com/okfn-brasil/querido-diario-deployment) — configuração de deployment
A API de produção utilizada por padrão é:
```text
https://api.queridodiario.org.br
```
Notas adicionais sobre o histórico dos endpoints estão em:
[`docs/upstream-api-history.md`](./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](https://github.com/lucaspmgomess/querido-diario-mcp-server/issues) 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:
```bash
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](./LICENSE)