🇺🇾 uruguay-mcp

Structured AI-agent access to Uruguay's open government data
Acceso estructurado de agentes de IA a los datos abiertos del Estado uruguayo

🌎 Español · English

An MCP server that gives AI agents structured access to Uruguay's open government data — the national data catalog, the Central Bank, the statistics institute, Montevideo's city data & realtime transport, spatial data (IDE), education, health, social programs, government social-security statistics (BPS), tax reference values (DGI), news, and the gub.uy service catalog — behind a single meta-discovery layer.

✨ Why a meta-discovery layer?

Instead of flooding the model with hundreds of tool definitions, the server exposes five meta-tools. The model searches for what it needs, then invokes the matching data tool by name. The prompt-visible surface stays constant no matter how many data sources are added.

Every tool returns a unified envelope: { "_meta": { source, cached, lang, timestamp }, "data": ... }.

At a glance: 5 meta-tools + 84 data tools across 17 modules, plus 54 prompts and 36 resources.

📚 Data sources (modules)

The transport surface of montevideo needs OAuth2 credentials (URUGUAY_MCP_MVD_CLIENT_ID / URUGUAY_MCP_MVD_CLIENT_SECRET); without them the transport tools return a typed validation_error while the CKAN tools work unauthenticated.

🧩 Prompts & Resources

Each module also registers reusable prompts (parameterized Spanish instruction templates) and resources (static reference docs under the uru://<module>/<path> URI scheme), exposed natively through FastMCP.

• 54 prompts — e.g. bcu_cotizacion_dolar_hoy, catalogo_buscar_por_tema, bps_pasividades_actuales, dgi_valor_referencia, ine_buscar_estudios, montevideo_proximo_bus, datastore_unir_dos_fuentes, acce_analizar_compra, impo_consultar_norma, inumet_clima_actual, ide_consultar_catastro, salud_consultar_medicamentos, noticias_ultimas.
• 36 resources — e.g. uru://bcu/codigos-moneda, uru://bps/catalogo-indicadores, uru://dgi/catalogo-valores, uru://catalogodatos/guia-de-uso, uru://montevideo/credenciales-transporte, uru://acce/glosario-ocds, uru://impo/esquema, uru://inumet/variables, uru://ide/capas-destacadas, uru://salud/fuentes, uru://mides/guia-recursos.

See EXAMPLES.md for end-to-end usage scenarios, including cross-source ones via plan_query / execute_batch and SQL JOINs through the datastore module.

🚀 Quick start

# Run directly from PyPI (once published)
uvx uruguay-mcp

# …or install it
pip install uruguay-mcp        # or: uv pip install uruguay-mcp
uruguay-mcp

One-command install into Claude

uruguay-mcp install

Merges the server into Claude Desktop's config (preserving existing mcpServers and unrelated keys) and prints a ready-to-paste snippet for Claude Code / Cursor. Restart the client afterwards.

Claude Desktop config (manual)

{
  "mcpServers": {
    "uruguay-mcp": { "command": "uruguay-mcp" }
  }
}

Run options

uruguay-mcp                          # stdio (default)
uruguay-mcp --transport sse --port 8000
uruguay-mcp --modules catalogodatos,bcu   # load only some modules
uruguay-mcp --verbose                # INFO logs   (--debug for DEBUG)

⚙️ Configuration

All via URUGUAY_MCP_* environment variables:

🏗️ Architecture

src/uruguay_mcp/
├── server.py            # FastMCP wiring; meta-tools + registered prompts + resources
├── cli.py               # `uruguay-mcp` / `uruguay-mcp install`; -v/--debug logging
├── meta/                # discovery layer
│   ├── tools.py         # the 5 meta-tools
│   └── search.py        # BM25-lite ranking over the registry
├── shared/              # reused by every module
│   ├── config.py        # env-driven settings (URUGUAY_MCP_*)
│   ├── http.py          # async client: retries (tenacity) + per-host rate limit
│   ├── cache.py         # async TTL cache
│   ├── envelope.py      # unified {_meta, data} response (+ UTC timestamp)
│   ├── i18n.py          # es/en messages
│   ├── errors.py        # typed, localized errors
│   └── registry.py      # tool/prompt/resource registry; @tool/@prompt/@resource
└── modules/             # one self-contained package per data source
    ├── catalogodatos/   ├── bcu/          ├── ine/
    ├── gubuy/           ├── montevideo/   ├── datastore/
    ├── acce/            ├── impo/         ├── inumet/
    ├── parlamento/      ├── ide/          ├── educacion/
    ├── salud/           ├── mides/        ├── noticias/
    ├── bps/             └── dgi/

Each module package is independent (constants · schemas · client · tools · optional prompts/resources). Importing the package self-registers everything it offers.

🛠️ Development

uv venv && uv pip install -e ".[dev]"

uv run pytest                  # 252 unit tests (HTTP mocked, offline) · 86% coverage
uv run pytest -m integration   # hits live government APIs
uv run ruff check src tests
uv run pyright

🙌 Acknowledgements

Built on data published by AGESIC, BCU, INE and the Intendencia de Montevideo under Uruguay's open-data law (Nº 18.381). This project is an independent client and is not affiliated with those institutions.

📄 License

MIT