Skip to main content
Glama
querido-diario-mcp-server

querido-diario-mcp-server

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.

Related MCP server: Prefeitura PE Recife: CPOM

Quick start

Requires Python 3.12+ and uv.

No repository clone is required:

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:

uvx querido-diario-mcp-server

Claude Desktop / Claude Code

{
  "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

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

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

Codex CLI

[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.

Tool

Purpose

search_cities

Search Brazilian municipalities by name and resolve the 7-digit IBGE territory ID. Supports an optional state filter.

get_city

Fetch one municipality by its exact 7-digit IBGE territory ID.

search_gazettes

Full-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:

Find mentions of ACME Ltda in Porto Alegre gazettes
from January through July 2026.

An MCP client can then execute:

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

MCP client
   |
   | stdio / MCP
   v
server.py
   |
   | validated tool arguments
   v
client.py
   |
   | typed read-only HTTPS requests
   v
Querido Diário public API

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

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

Variable

Default

Purpose

QD_API_BASE_URL

https://api.queridodiario.org.br

Base 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:

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

Run the same checks enforced by CI:

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

Run the server from the checkout:

uv run querido-diario-mcp-server

Inspect the MCP tools interactively:

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:

uv run python scripts/smoke_test_api.py
uv 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

Available Tools

3 tools
get_cityA

Retrieve one Brazilian municipality by its 7-digit IBGE territory ID.

Use this when the exact territory_id is already known (from `search_cities`, or
supplied directly) and you need that city's details: name, state, Querido Diário
availability date, and known official publication URLs. If you only have a city
name, call `search_cities` instead.

Inputs: territory_id (required). Returns: A Brazilian municipality known to Querido Diário.

search_citiesA

Find Brazilian municipalities indexed by Querido Diário and resolve their 7-digit IBGE territory IDs.

Call this FIRST whenever a request names a city but you don't already have its
numeric territory ID — both `get_city` and `search_gazettes` require that ID, not
a city name. For example, to answer "find gazettes about ACME in Porto Alegre",
first call search_cities(city_name="Porto Alegre") to get its territory_id, then
pass that ID to search_gazettes.

Matching is by partial, case-insensitive name similarity (as implemented by the
upstream API), not exact string equality, so it tolerates minor spelling
variation. `state_code` is an optional two-letter Brazilian state/UF filter
(e.g. "RS", "SP") applied after the upstream search, useful for disambiguating
cities that share a name across different states.

Inputs: city_name (required), state_code. Returns: Response body of `GET /cities`.

search_gazettesA

Search the text of published Brazilian municipal official gazettes.

Each result is one gazette (one city's official publication, one edition, one
date) with a short excerpt showing where `query` matched. This searches gazette
*content*, not city metadata — resolve a city name to its territory_id with
`search_cities` first.

`query` uses OpenSearch's "simple query string syntax": bare words are OR'd
together, a leading `+` requires a term, a leading `-` excludes it, and double
quotes match an exact phrase — e.g. '"João da Silva"' for an exact name, or
'+licitação +pregão' to require both terms together. An empty query returns
matching gazettes' metadata without excerpts.

`territory_ids` restricts the search to specific cities by their 7-digit IBGE ID
(from `search_cities` or `get_city`); omit it to search across all available
cities. `published_since` / `published_until` are inclusive ISO dates
(YYYY-MM-DD) bounding the gazette's publication date — leave both unset to search
the full available history. `size` is capped at 50 results per call; use `offset`
to page through more. `sort_by` defaults to relevance; use "descending_date" or
"ascending_date" to sort chronologically instead.

Example: to find mentions of "Empresa X" in Porto Alegre gazettes published
between January and July 2026, once territory_id "4314902" is known, call
search_gazettes(query='"Empresa X"', territory_ids=["4314902"],
published_since="2026-01-01", published_until="2026-07-31").

Inputs: size, query, offset, sort_by, +3 more. Returns: Response body of `GET /gazettes`.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.8/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct role: search_cities resolves city names to IDs, get_city retrieves metadata by ID, and search_gazettes searches gazette content. No two tools overlap in purpose or output.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: search_cities, get_city, search_gazettes. The singular/plural difference for 'city' is natural and does not create confusion.

    Tool Count5/5

    Three tools is a well-scoped set for a focused gazette search server. Each tool is necessary and covers a distinct step in the core workflow: resolve city, inspect city, search gazettes.

    Completeness4/5

    The core search workflow is fully covered: city name resolution, city detail lookup, and gazette full-text search with filtering. Minor gaps exist (e.g., no direct single-gazette fetch endpoint or full-text retrieval beyond excerpts), but they do not break the primary use case.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables querying official data from the Prefeitura de Recife (Recife City Hall) through a hosted, read-only MCP server. Supports MCP over HTTP with usage-based prepaid billing.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Provides read-only access to Brazilian municipality codes from IBGE, an official government source, via MCP. Works with any MCP-compatible client to query municipality data using natural language.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to query Brazilian municipal transparency portals for payroll, expenses, contracts, bids, revenues, and legislation using natural language in Portuguese.
      MIT