uruguay-mcp 0.1.1

MCP server for Uruguay's open government data (national catalog, BCU, INE, Montevideo, gub.uy)

🇺🇾 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, 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.

Meta-tool	Purpose
discover_tools(query, module?, limit?)	Rank data tools relevant to a natural-language need (returns their argument schemas)
call_tool(name, arguments)	Invoke a data tool by name (validates arguments)
list_modules()	List data-source modules and their tool counts
plan_query(goal)	Surface candidate tools for a multi-step goal
execute_batch(calls)	Run several calls concurrently with per-call error isolation

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

At a glance: 5 meta-tools + 31 data tools across 6 modules, plus 17 prompts and 11 resources.

📚 Data sources (modules)

	Module	Source	Protocol	Tools
🏛️	catalogodatos	catalogodatos.gub.uy — national CKAN catalog (~2680 datasets, 72 orgs)	CKAN REST	5
💵	bcu	Banco Central del Uruguay — exchange rates	SOAP (zeep)	4
📊	ine	Instituto Nacional de Estadística — ANDA / microdata	REST	3
🌐	gubuy	gub.uy public API / service catalog	CKAN REST	4
🚌	montevideo	Intendencia de Montevideo — city CKAN + realtime transport	CKAN + REST	11
🗄️	datastore	Cross-source SQLite workspace — load CSV/CKAN data, run read-only SQL JOINs	local SQLite	4

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.

• 17 prompts — e.g. bcu_cotizacion_dolar_hoy, catalogo_buscar_por_tema, ine_buscar_estudios, montevideo_proximo_bus, datastore_unir_dos_fuentes.
• 11 resources — e.g. uru://bcu/codigos-moneda, uru://catalogodatos/guia-de-uso, uru://montevideo/credenciales-transporte.

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:

Variable	Default	Meaning
URUGUAY_MCP_LANG	es	Language for human-facing strings (es/en)
URUGUAY_MCP_HTTP_TIMEOUT	30	HTTP timeout (seconds)
URUGUAY_MCP_CACHE_TTL	900	Response cache TTL (seconds)
URUGUAY_MCP_RATE_LIMIT_RPS	5	Max requests/sec per host
URUGUAY_MCP_MODULES	(all)	Comma-separated module allowlist
URUGUAY_MCP_MVD_CLIENT_ID	(unset)	OAuth2 client id for the Montevideo transport API
URUGUAY_MCP_MVD_CLIENT_SECRET	(unset)	OAuth2 client secret for the Montevideo transport API

🏗️ 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/

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                  # 69 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