Querido Diário MCP Server

io.github.lucaspmgomessPublished by GitHub account lucaspmgomessv0.1.0Updated Oct 24, 2026

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

VerifiedSTDIODesktop onlyLocation & LifestyleWeb Search & Scraping

Overview

AI-generated overview

Local read-only MCP server that lets an assistant look up Brazilian municipalities and search indexed municipal official gazettes via the public Querido Diário.

What you can do
Resolve Brazilian municipalities by name or state and get their 7-digit IBGE territory IDs, or fetch one city by exact ID. Full-text search indexed municipal gazettes with municipality, publication date range, pagination and sorting filters, using simple query syntax such as required terms, excluded terms and exact phrases. Receive structured results that can be summarized, filtered or combined with other tools.
When to use it
Useful when you need to find mentions of a company, person or topic in Brazilian municipal official gazettes, or to map city names to IBGE territory IDs before searching. It is a narrow, read-only research tool rather than a general web or document fetcher.
Requirements
Runs locally over stdio as a PyPI package; requires Python 3.12+ and uv, launched with the uvx command from an MCP client. No API key or account. Network access to the public Querido Diário API is needed; the optional QD_API_BASE_URL variable overrides the API base URL and is not needed by normal users.
Before you install
Unofficial community project, not endorsed by Open Knowledge Brasil, and in beta. It only reads from the public API and does not fetch gazette URLs, download PDFs, run OCR or write data. Search queries and city lookups are sent to the third-party Querido Diário API; setting QD_API_BASE_URL points it at a different endpoint.

Installation

In SourceWeft

  1. Open Querido Diário MCP Server in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

Querido Diário MCP Server

[PyPI] [Python] [CI] [MCP Registry] [License: MIT]

A local-first Model Context Protocol server that gives AI clients structured, read-only access to Brazilian municipal official gazettes indexed by Querido Diário.

No API key · Runs locally · Read-only · No telemetry · Open source

🇧🇷 Versão em português

The package is published on PyPI and the MCP Registry.

What it does

Querido Diário provides searchable municipal official gazettes through a public API. This server exposes a small, typed MCP interface on top of that API so an MCP client can:

  • resolve Brazilian municipalities and their IBGE territory IDs;
  • search indexed official gazettes by text, municipality and date range;
  • receive structured results that are easier for agents to inspect and combine with other tools.

The server runs as a local stdio subprocess and only performs read-only HTTPS requests to the public Querido Diário API.

Quick start

Requires Python 3.12+ and uv.

No repository clone is required:

bash
uvx querido-diario-mcp-server

This starts the MCP server on stdio. It is intended to be launched by an MCP client rather than used as an interactive terminal application.

Client configuration

All supported clients use the same command:

text
uvx querido-diario-mcp-server

Claude Desktop / Claude Code

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

Use this in claude_desktop_config.json for Claude Desktop or a project-level .mcp.json for Claude Code.

Cursor

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

Add it to .cursor/mcp.json or your global Cursor MCP configuration.

Codex CLI

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

Other MCP clients that support local stdio servers can launch the same command.

Tools

The server intentionally exposes a small, read-only tool surface.

ToolPurpose
search_citiesSearch Brazilian municipalities by name and resolve the 7-digit IBGE territory ID. Supports an optional state filter.
get_cityFetch one municipality by its exact 7-digit IBGE territory ID.
search_gazettesFull-text search over indexed gazettes with municipality, publication date, pagination and sorting filters.

search_gazettes uses the simple-query-string syntax supported by the upstream search API. Examples include +required, -excluded and "exact phrase".

Example

A user can ask:

text
Find mentions of ACME Ltda in Porto Alegre gazettesfrom January through July 2026.

An MCP client can then execute:

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",   )

The result is returned as structured tool output for the client to summarize, filter or combine with other tools.

Architecture

text
MCP client   |   | stdio / MCP   vserver.py   |   | validated tool arguments   vclient.py   |   | typed read-only HTTPS requests   vQuerido Diário public API

The implementation keeps the protocol boundary separate from the HTTP integration:

text
src/querido_diario_mcp_server/    __init__.py   package version and CLI entry point    config.py     environment-driven configuration    errors.py     integration error hierarchy    models.py     typed Pydantic domain models    client.py     async HTTP client with no MCP dependency    server.py     MCP lifespan, validation and tool definitions

A single httpx.AsyncClient connection pool is created for the server lifecycle and reused across tool calls. The HTTP client can be tested independently of MCP, while integration tests exercise the real MCP server in process.

Design principles

  • Read-only by design. The integration only calls a fixed set of upstream GET endpoints.
  • Local-first. There is no hosted middleware, proprietary backend or account requirement.
  • Typed boundaries. API responses and MCP outputs use explicit Pydantic models.
  • Small tool surface. The server exposes only the operations required to discover cities and search gazettes.
  • Explicit failures. Upstream failures are converted to concise MCP tool errors rather than raw tracebacks or HTML responses.
  • No arbitrary URL fetching. Tool callers cannot turn the server into a generic HTTP or SSRF primitive.
  • No telemetry. The server does not collect usage data.

Security

The server never automatically follows gazette URLs returned by the upstream API and does not accept arbitrary target URLs from tool callers. Territory IDs, dates, pagination and sort options are validated before use.

For vulnerability reporting and the supported security scope, see SECURITY.md.

Configuration

VariableDefaultPurpose
QD_API_BASE_URLhttps://api.queridodiario.org.brBase URL for the Querido Diário API. Can be overridden for local or staging environments.

Normal users do not need to set any environment variables.

Development

Clone the repository only if you want to contribute or work on the implementation:

bash
git clone https://github.com/lucaspmgomess/querido-diario-mcp-server.gitcd querido-diario-mcp-serveruv sync

Run the same checks enforced by CI:

bash
uv run ruff check .uv run ruff format --check .uv run pyrightuv run pytest --cov

Run the server from the checkout:

bash
uv run querido-diario-mcp-server

Inspect the MCP tools interactively:

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

Test strategy

Unit tests mock the HTTP boundary with httpx.MockTransport, so the automated suite does not depend on the public API.

Coverage includes:

  • successful city and gazette searches;
  • query serialization and repeated territory IDs;
  • date ranges, pagination and sorting;
  • empty result sets;
  • 4xx and 5xx upstream failures;
  • malformed responses;
  • connection errors and timeouts;
  • MCP tool discovery, schemas and structured outputs;
  • validation errors and upstream failures at the MCP boundary.

Manual smoke-test scripts are available for validating the real production API and the full MCP-to-API path:

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

Project status

The project is currently in beta. The MCP tool surface is intentionally small and changes are kept conservative. Release history is documented in CHANGELOG.md.

The following are intentionally outside the current scope:

  • arbitrary URL fetching;
  • automatic PDF or full-text download;
  • OCR;
  • write operations;
  • crawling and background jobs;
  • built-in LLM summarization;
  • a web interface.

Relationship to Querido Diário

This is a community-built, unofficial project.

Querido Diário is maintained by Open Knowledge Brasil and its community. This repository is not an official Open Knowledge Brasil project, is not endorsed or maintained by the organization, and only consumes the project's public API.

Relevant upstream repositories:

Additional notes about upstream endpoint history are kept in docs/upstream-api-history.md.

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md for the development workflow, project scope and review checklist.

License

MIT

Source: README.md at commit eba1c33

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts