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