English · Español

---

datosgobdo-mcp

A Model Context Protocol server that exposes the Dominican Republic's open government data (datos.gob.do) as tools consumable by any AI assistant.

It turns the official Dominican open-data portal into a native integration for Claude Desktop, Claude Code, Cursor, ChatGPT Desktop or any MCP-compatible client. The model can search, read, analyze, and preview the 1,053+ datasets published by the country's 266 government institutions, all from within a conversation.

Official source. The canonical repository is alcastaro/datos.gob.do-MCP-server. The only official distributions are the PyPI package dominican-open-data-mcp and the MCP Registry entry io.github.alcastaro/datos.gob.do-MCP-server. Copies published elsewhere are not maintained by the author and may be outdated or modified — verify against this repository before installing.

📚 New here? Read the Tutorial — how the server works, how to use it, and how to build your own MCP server like it. (Español)

---

What problem does it solve?

datos.gob.do publishes thousands of CSV, XLSX, and JSON files with public data: payrolls, budgets, crime statistics, health indicators, electoral data, and more. Today that information is only accessible to people who know how to navigate the CKAN portal and download files manually.

This MCP closes that gap. Anyone can ask their assistant:

• "How much does the Judicial Branch spend on salaries?"
• "Compare FONDOMARENA's approved vs. executed budget over the last three years."
• "List the 10 institutions that publish the most data."
• "What columns does the Ministry of Interior's vehicle-theft dataset have?"

…and the model — without the user having to write code, navigate URLs, or download files — runs the actual queries against the portal, downloads the data, parses it, and analyzes it.

Who is it for?

• Data journalists wanting to explore official sources without writing scrapers.
• Researchers and academics needing programmatic access to Dominican government data.
• Transparency activists and civil society monitoring budget execution, procurement, and public administration.
• Developers and data scientists prototyping dashboards or analyses on public data.
• Public officials wanting to query what their own (or other) institutions already publish.
• Anyone with civic curiosity about how the government operates.

What is MCP?

Model Context Protocol is an open standard (created by Anthropic, adopted by OpenAI and others) that lets language models connect securely to external data sources and tools. An "MCP server" exposes a collection of typed functions; the model decides when to invoke them, with what arguments, and how to combine the results.

This project is an MCP server specialized in datos.gob.do.

What is datos.gob.do?

The official open-data portal of the Dominican government, operated by OGTIC (the country's IT and communications office). It runs on CKAN 2.11.3, the same open-data software used by portals like data.gov (USA), data.gov.uk, and many other Latin American governments.

As of May 2026 it contains approximately:

• 1,053 datasets published
• 266 organizations publishing (ministries, municipalities, autonomous agencies, etc.)
• 11 thematic categories (Economy, Health, Education, Public Management…)
• 852 tags

Each dataset bundles one or more "resources" (downloadable files) in formats such as CSV, XLSX, ODS, PDF, or JSON.

This MCP is inspired by datagouv-mcp (France), but datos.gob.do runs a different platform (CKAN, not udata), so the implementation is its own.

---

Tools exposed

24 typed functions, grouped into five categories. The data-producing tools (analytics + preview + cache) return typed outputSchema / structuredContent, so MCP hosts can validate results; navigational metadata tools return JSON.

Discovery

Tool	What it does
search_datasets	Search datasets by keyword, organization, tag, or group. Combinable filters, pagination.
get_dataset	Return full metadata for a dataset: title, description, license, author, and the complete list of its resources with direct download URLs.
list_recent_datasets	Datasets sorted by most-recent modification. Useful for monitoring portal updates.
get_site_stats	Portal-wide counts (totals of datasets, organizations, groups, tags).

Resources (files)

Tool	What it does
get_resource	Metadata for a single resource (URL, format, size, date).
search_resources	Search resources by name.
download_resource_preview	Download a file and return N rows. CSV, TSV, XLSX, XLS, JSON. 5 MB cap. Sample mode: head / tail / random.
check_resources	Ask up to 25 URLs whether their files can actually be downloaded, without downloading them. Returns a class per URL — reachable, browser challenge, site rule, dead link, no answer — because a catalog entry is not evidence the file is still there.

Analytics (v0.2+)

DuckDB-backed analytics over a persistent Parquet cache. First call per resource downloads + caches (up to 100 MB). Subsequent calls are sub-second.

Tool	What it does
get_resource_schema	Column names, inferred types, sample values per column. Cheap reconnaissance step before any aggregation.
summarize_resource	Auto-generated profile: row count, per-column nulls/distinct, min/max/mean on numerics, top-N values on categoricals.
filter_resource	Typed WHERE / SELECT / ORDER BY / LIMIT. Ops: =, !=, <, <=, >, >=, in, not_in, contains, starts_with, ends_with, is_null, is_not_null.
aggregate_resource	Typed GROUP BY + aggregations + HAVING + ORDER BY. Fns: count, count_distinct, sum, avg, mean, median, min, max, stddev, variance.
query_resource	Power-user escape hatch: read-only SQL against table data. SELECT/WITH only; DDL/DML/COPY/PRAGMA/ATTACH/LOAD rejected. Sandboxed — the resource is materialized in memory with external access disabled, so table functions cannot read local files or reach the network.
quantiles_resource	Percentile distribution (p25/p50/p75/p90/p95/p99) of numeric columns. Use before aggregate_resource for statistical profiling.
find_duplicates_resource	Find rows duplicated on specified columns (or all columns). Essential for payroll and census data-quality checks.
detect_outliers_resource	Find rows outside the IQR fence on a numeric column. Returns rows sorted by distance from median.
save_query_to_csv	Write a filter or SQL result to a local CSV file. Default destination: ~/Downloads/datosgobdo-exports/.
get_cache_stats	On-disk Parquet cache stats.
clear_cache	Wipe the local Parquet cache.

Catalog

Tool	What it does
list_organizations	All publishing institutions, with a dataset count per institution.
get_organization	Detail for a single institution (description, dataset count, URL).
list_groups	Thematic categories with dataset counts.
list_tags	Available tags, optionally filtered by prefix.

Autocomplete

Tool	What it does
autocomplete	Resolve partial names for datasets, organizations, groups, or tags. Useful when the user only gives a partial name.

GCP pipeline (optional — pip install 'dominican-open-data-mcp[gcp]')

Three extra tools register automatically when the google-cloud libraries are installed. They turn the server into the ingestion half of a BigQuery pipeline: discover datasets here, load them to BigQuery, then query them with Google's official BigQuery MCP (cross-dataset JOINs local DuckDB cannot do).

Tool	What it does
load_resource_to_bigquery	Resource → Parquet cache → GCS upload → BigQuery External Table (default, zero-ETL) or Load Job.
list_bigquery_exports	List tables in a BigQuery dataset.
get_bigquery_table_info	Schema, row count and source URIs of a table.

Set DATOSGOBDO_GCS_BUCKET to avoid passing the bucket on every call.

What the answers tell you about themselves

Three fields appear in responses when the server had to do something the caller did not ask for. Each exists because a tool used for auditing must not quietly paper over a defect in the data.

numeric_coercion — a column stored as text was read as numbers.

This is the most common defect in the Dominican catalog: 93 of 540 readable resources hold numeric columns as text, because a handful of cells say N/A or #REF! and that is enough to make a whole payroll column non-numeric. aggregate_resource, quantiles_resource and detect_outliers_resource read such a column as numbers where each value permits it, and report what that cost:

"numeric_coercion": [{
  "column": "SUELDO BRUTO (RD$)", "coerced": true,
  "values_used": 21469, "values_excluded": 37,
  "excluded_values": [{"value": "N/A", "count": 21}, {"value": "#REF!", "count": 16}]
}]

Read values_excluded before quoting the total. A column under 90 % parseable is left as text and the reply says why, rather than answering a question about a measure from an arbitrary subset of rows.

linked_files — the URL served a page, and the page linked data files.

37 catalog resources answer with a web page instead of a file. When one linked file clearly matches what was requested, it is fetched and cache.resolved_from records {page, followed} — you asked for one URL and received data from another, which the reply says rather than hides. When several candidates are indistinguishable, they come back as linked_files with names and scores, for you to choose and call again. Real files named clss.csv and xls.csv exist in this catalog; guessing between them would be inventing.

cache.provenance — the answer came from an archived copy, not the portal. See Archived copies below.

Security: outbound download guard

Every resource download is validated by an SSRF guard (initial URL and each redirect hop): http/https only, and every address the host resolves to must be publicly routable (cloud metadata, loopback and private ranges are blocked). Environment knobs:

Variable	Values	Meaning
DATOSGOBDO_NETGUARD	public-only (default) / strict / off	strict restricts hosts to datos.gob.do; off disables the guard.
DATOSGOBDO_ALLOW_HOSTS	comma-separated, *. wildcards	Operator-trusted hosts (e.g. forks pointing at another CKAN portal).

Archived copies (optional)

Government links rot. A census of the whole catalog on 2026-08-08 found 15 resource URLs already dead and 99 institutions whose sites had grown rules that refuse programmatic access, so a figure you cite today may be uncheckable next year.

Point DATOSGOBDO_ARCHIVE_DIR at a directory holding a manifest.json and its Parquet files, and when a portal cannot be reached the server answers from the archived copy instead. It is off by default, the portal is always tried first, and the reply always says so — cache.provenance carries the capture date, the sha256, the licence and why the origin was not used. A tool that quietly returned yesterday's copy as though it were today's would stop being useful for an audit.

An archive only holds what could be downloaded, so it does not contain the resources a portal refuses. That is the natural assumption and it is wrong.

Variable	Default	Meaning
DATOSGOBDO_ARCHIVE_DIR	unset (off)	Directory with manifest.json + Parquet copies to fall back on.

Hosted mode (experimental)

DATOSGOBDO_TRANSPORT=streamable-http serves MCP over HTTP (stateless, for horizontal scaling) instead of stdio. In this mode save_query_to_csv and clear_cache are disabled (they touch the server's filesystem / shared cache) and cache stats omit server paths.

Variable	Default	Meaning
DATOSGOBDO_TRANSPORT	stdio	streamable-http for hosted deployments.
DATOSGOBDO_HOST / DATOSGOBDO_PORT	127.0.0.1 / 8000	HTTP bind address.
DATOSGOBDO_DUCKDB_MEMORY	2GB	DuckDB memory ceiling per connection.
DATOSGOBDO_DUCKDB_THREADS	4	DuckDB thread cap.
DATOSGOBDO_QUERY_TIMEOUT	0 (off)	Wall-clock seconds before a DuckDB run is interrupted. Covers both query_resource SQL and the conversion of a freshly downloaded file into the Parquet cache.

---

Installation and configuration

Option A — Via uvx from PyPI (recommended)

Package: dominican-open-data-mcp.

uvx dominican-open-data-mcp

The package also ships a short binary, datosgobdo-mcp — both commands launch the same server:

uvx --from dominican-open-data-mcp datosgobdo-mcp

uvx downloads the package, creates an isolated venv, and runs the server. First run takes a few seconds; subsequent runs are instant.

Upgrading from ≤ 0.7.0? Those releases pinned mcp>=1.9.0 with no upper bound, and the MCP Python SDK 2.0 (released 2026-07-28) removed the mcp.server.fastmcp import path — so a fresh install fails with ModuleNotFoundError. Install 0.7.1 or later, or pin the SDK yourself: uvx --with "mcp<2" --from dominican-open-data-mcp datosgobdo-mcp.

Option B — Via uvx from GitHub (latest dev version)

uvx --from git+https://github.com/alcastaro/datos.gob.do-MCP-server.git datosgobdo-mcp

Prerequisite: uv installed. On macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Option C — Local clone (for development)

git clone https://github.com/alcastaro/datos.gob.do-MCP-server.git
cd datos.gob.do-MCP-server
uv sync
uv run datosgobdo-mcp   # starts the server on stdio (Ctrl+C to exit)

macOS note: avoid cloning inside ~/Library/CloudStorage/GoogleDrive-* or similar paths. macOS blocks executing binaries from cloud-synced paths (TCC restriction). Use ~/code/ or equivalent.

Claude Desktop configuration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "datosgobdo": {
      "command": "/Users/YOUR_USERNAME/.local/bin/uvx",
      "args": ["dominican-open-data-mcp"]
    }
  }
}

Use the absolute path to uvx — Claude Desktop does not inherit your shell PATH. To track the development version instead, replace the args with ["--from", "git+https://github.com/alcastaro/datos.gob.do-MCP-server.git", "datosgobdo-mcp"].

Restart Claude Desktop completely (Cmd+Q, not just closing the window). Settings → Developer → Local MCP servers should show datosgobdo in running state.

Claude Code configuration

claude mcp add datosgobdo -- uvx dominican-open-data-mcp

Development version: claude mcp add datosgobdo -- uvx --from git+https://github.com/alcastaro/datos.gob.do-MCP-server.git datosgobdo-mcp

Cursor / other clients

Same principle: register uvx as the command with --from git+... datosgobdo-mcp as args. Consult each client's docs for the location of its configuration file.

---

Usage examples

Once configured, you can ask the model:

Basic exploration

Use the datosgobdo MCP and tell me how many datasets are on the datos.gob.do portal.

→ Invokes get_site_stats. Reply: 1,053 datasets, 266 organizations.

Search with analysis

Find the 5 most relevant datasets about budget on datos.gob.do and summarize which institution publishes each one.

→ Invokes search_datasets(query="presupuesto", limit=5) and the model writes the summary.

Name resolution + detail

Find the slug for the Ministry of Finance and tell me how many datasets it has published.

→ autocomplete(kind="organization", query="hacienda") → get_organization(id="ministerio-de-hacienda").

Real data analysis

Show me the first 20 rows of the Judicial Branch budget CSV and tell me the three largest line items.

→ search_datasets(query="poder judicial") → get_dataset("presupuesto-poder-judicial") → download_resource_preview(url=..., format="csv", rows=20) → the model identifies the largest items.

Big-file analytics (v0.2+)

How many active employees are there at the Ministry of Agriculture in April 2026, broken down by employment status?

The Agricultura nómina CSV has 826,000 rows and 94 MB — too big for the preview tool. The analytics workflow:

→ search_datasets(query="nomina agricultura") → get_dataset(...) → get_resource_schema(url, "csv") to see columns (Nombre, Departamento, Función, Estatus, Sueldo Bruto, Mes, Año) → aggregate_resource(...) with group_by=["Estatus"], filters on Año=2026, Mes='Abril', and count_distinct on Nombre.

Result: 6 status types, total ~8,915 employees. Cold first call: ~14 s (download + Parquet conversion). Subsequent calls on the same file: <0.5 s (cache hit).

Monitoring

List the 10 most recently updated datasets on the portal.

→ list_recent_datasets(limit=10).

---

Architecture

src/datosgobdo_mcp/
  server.py        FastMCP server + tool definitions (Pydantic typed)
  ckan.py          CKAN client: requests, Solr escaping, formatters
  preview.py       Capped file download + parsers for CSV/XLSX/JSON

Design decisions

• FastMCP instead of the low-level SDK: tools are functions decorated with @mcp.tool() and typed via Pydantic. Less boilerplate, automatic argument validation.
• Reused httpx.AsyncClient: a single persistent connection, no TCP-handshake overhead per request.
• Solr escaping: CKAN fq filters use Solr/Lucene syntax. User-supplied values go through _escape_solr(), which escapes the 13 reserved characters (+ - & | ! ( ) { } [ ] ^ " ~ * ? : \ /). Without this, a tag containing a quote would break the query.
• Defensive truncation: long descriptions (some institutions publish 5+ KB of text per organization) are truncated to 300 chars in list responses. Without this, a single call could burn thousands of tokens of model context.
• list_recent_datasets reoriented: CKAN's API exposes recently_changed_packages_activity_list, but it returns "activities" with raw, un-hydrated metadata — the model would receive {object_id: "uuid", activity_type: "changed package"} with no way to know which dataset it refers to. We use package_search?sort=metadata_modified+desc to return already-formatted datasets in a single call.
• DataStore not available: the datos.gob.do portal does not have the DataStore extension installed, so there is no datastore_search endpoint or SQL queries against resource contents. The workaround is download_resource_preview: we download the file (5 MB cap) and parse it client-side with csv (stdlib) or openpyxl. Enough for the model to understand the structure.
• Encoding fallback: many published files are in CP1252 or Latin-1 (not UTF-8). The parser tries UTF-8 → UTF-8-sig → Latin-1 → CP1252 → UTF-8 with errors=replace.
• stderr logging: per the MCP debugging guide, stdio servers must never write to stdout (it breaks the protocol). All logs go to stderr and are captured by the client in ~/Library/Logs/Claude/mcp-server-datosgobdo.log (macOS).

Technical stack

• mcp — Anthropic's official Python SDK (FastMCP)
• httpx — async HTTP client
• openpyxl — read-only streaming XLSX reader
• csv, json — stdlib for other formats

---

Known limitations

Measured against the whole catalog on 2026-08-08 — 1,056 resources, one per dataset — rather than estimated.

Not everything published is reachable. 540 of 1,056 resources could be read. The largest cause is not this server: 360 resources across 99 institutions sit behind a site configuration that refuses programmatic downloads of files those same institutions publish as open data. From one address, 21 other government hosts behind the same CDN serve us normally, so it is per-site configuration rather than our network. No version of this server can change that. A further 15 links are dead, 37 serve a web page, and 8 files are corrupt.

Formats. CSV, XLSX and ODS all read at ~93 %. Two are weaker: legacy .xls, and JSON — DuckDB's read_json_auto rejects several catalog files as malformed, so JSON is the least reliable format here.

Size. download_resource_preview caps at 5 MB; the analytics tools raise it to 100 MB. A single value larger than 16 MB exceeds DuckDB's limit and the file cannot be parsed.

Shape. 41 resources put titles or logos above the real header row, which garbles the auto-detected schema; inspect with download_resource_preview and project columns explicitly with query_resource. 93 hold numbers as text — handled, see What the answers tell you about themselves.

Encoding is effectively solved: one file in 540 still shows damaged accents, and that file is encoded in two codepages at once, so no single reading is correct for it.

Read-only by design. No authentication, no package_create or resource_create. PDF is not parsed; only its download URL is exposed.

Untested, and therefore not claimed: the hosted streamable-http transport, the three GCP tools against a live project, Windows, and concurrent use.

Development

Local setup

git clone https://github.com/alcastaro/datos.gob.do-MCP-server.git
cd datos.gob.do-MCP-server
uv sync

Test with the MCP Inspector

MCP Inspector is the official tool for testing MCP servers in isolation:

npx @modelcontextprotocol/inspector uv run datosgobdo-mcp

Opens http://localhost:6274 with a form builder to invoke tools manually and see raw request/response JSON.

Logs

In Claude Desktop (macOS): tail -f ~/Library/Logs/Claude/mcp-server-datosgobdo.log

The server logs to stderr:

• Startup (endpoint, number of registered tools)
• Fatal errors with full traceback
• Shutdown

Iteration

When you edit code:

1. Commit + push to main on GitHub.
2. Clear the uvx cache to force a refresh: uv cache clean dominican-open-data-mcp (the cache is keyed on the distribution name, not the binary name).
3. Restart the MCP client.

For faster iteration, configure the client to point to your local clone instead of the GitHub repo: command: /path/to/clone/.venv/bin/datosgobdo-mcp.

Manual tests against the live API

uv run python -c "
import asyncio
from datosgobdo_mcp import ckan
print(asyncio.run(ckan.get_site_stats()))
asyncio.run(ckan.close_client())
"

---

Contributing

Pull requests welcome. Obvious areas for improvement:

• Automated tests with pytest-httpx (mocking CKAN).
• summarize_csv tool with aggregate statistics (count, min, max, distinct values per column).
• Preview support for ODS and Parquet.
• Local cache of frequent responses (organizations, groups, tags change rarely).
• find_dataset_about tool that combines autocomplete + search_datasets with semantic ranking.

---

Credits

Developed by Alberto Castillo Aroca (@alcastaro) with contributions from Juana Casique (@juanacasique).

Data published by the institutions of the Dominican State via datos.gob.do, a portal operated by OGTIC.

Inspired by datagouv-mcp (Etalab, Government of France).

License

MIT. See LICENSE if present, otherwise assume standard MIT terms.

Data accessed through this MCP is subject to the license under which each Dominican institution publishes it on datos.gob.do (typically Open Data Commons Open Database License — ODbL).