# Querido Diário MCP Server [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/lucaspmgomess/querido-diario-mcp-server  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/querido-di-rio-mcp-server

## Description
Unofficial, read-only MCP server for the public Querido Diário API (Brazilian municipal gazettes)

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation & 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.**

[![PyPI](https://img.shields.io/pypi/v/querido-diario-mcp-server.svg)](https://pypi.org/project/querido-diario-mcp-server/)
[![Python](https://img.shields.io/pypi/pyversions/querido-diario-mcp-server.svg)](https://pypi.org/project/querido-diario-mcp-server/)
[![CI](https://github.com/lucaspmgomess/querido-diario-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/lucaspmgomess/querido-diario-mcp-server/actions/workflows/ci.yml)
[![MCP Registry](https://img.shields.io/badge/MCP%20Registry-published-brightgreen)](https://registry.modelcontextprotocol.io/?q=io.github.lucaspmgomess%2Fquerido-diario-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)

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

> 🌎 **English version:** [README.en.md](https://github.com/lucaspmgomess/querido-diario-mcp-server/blob/HEAD/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`](https://github.com/lucaspmgomess/querido-diario-mcp-server/blob/HEAD/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](https://github.com/lucaspmgomess/querido-diario-mcp-server/blob/HEAD/LICENSE)