opendata-ua-mcp

opendata-mcp — data.gov.ua MCP server

Українською

An open-source MCP server that lets any MCP-compatible AI agent search and analyze Ukraine's national open-data portal data.gov.ua in natural language.

It speaks the Model Context Protocol, so it works with any client that supports MCP — including Claude (Desktop / Code), ChatGPT (Developer Mode / custom connectors), Google Gemini, Cursor, Cline / Continue, VS Code Copilot, local models via Ollama / LM Studio, and your own agents built on the Python/TypeScript MCP SDKs. Not tied to any single vendor.

Phase 1: read-only, public endpoints — no API token, no auth required.

Design

Tools are jobs-to-be-done, not thin API wrappers. Each tool does a complete user task, composes several CKAN calls internally, hides portal quirks (UUID slugs, dirty formats, sparse DataStore, Unicode homoglyphs), and returns a token-efficient slim result (a search hit is ~150 B vs ~17 KB raw).

| Tool | What it does | |---|---| | find_datasets | Find datasets by topic; ranked slim candidates + refine hints | | explore_catalog | Aggregate view (who publishes / how much) — counts only | | inspect_dataset | Full dataset card: license, freshness, resources | | get_dataset_data | Get the actual data — auto-picks best resource; DataStore or download+parse CSV/JSON/XLSX/XML, including files inside ZIP archives (ЄДР, debtors registries) | | filter_data | Filter rows / read-only SQL over a structured (DataStore) resource | | track_updates | Recently updated datasets, filterable by topic/org |

Install

The server runs over stdio, the transport every MCP client understands. The config below is the same everywhere — only the file/menu where you paste it differs per client.

Any MCP client (npm) — universal

{
  "mcpServers": {
    "opendata-ua": {
      "command": "npx",
      "args": ["-y", "@opendata-ua/mcp-server"]
    }
  }
}

Where to put it:

| Client | Location | |---|---| | Claude Desktop | Settings → Developer → Edit Config (claude_desktop_config.json) | | Claude Code | claude mcp add opendata-ua -- npx -y @opendata-ua/mcp-server | | ChatGPT | Settings → Connectors → add MCP server (Developer Mode) | | Google Gemini | Gemini CLI / SDK mcpServers config | | Cursor | Settings → MCP → Add Server (~/.cursor/mcp.json) | | Cline / Continue / VS Code | the extension's MCP settings | | Custom agent | point your MCP SDK at npx -y @opendata-ua/mcp-server |

Claude Desktop — one-click DXT

DXT is Claude Desktop's drag-and-drop bundle format:

1. Download opendata-ua-mcp.dxt from Releases.
2. Drag it into Claude Desktop → Settings → Extensions. Done. No config.

From source

npm install
npm run build
node dist/stdio.js   # any MCP client can spawn this

Try it

"Find ecology datasets from Lviv published in 2024" "Which organizations publish the most procurement data?" "Show me the first rows of the stolen-vehicles register"

Configuration (optional)

| Env var | Default | Purpose | |---|---|---| | DATA_GOV_UA_BASE_URL | https://data.gov.ua/api/3/action | API base (mirror/dev portal) | | CACHE_TTL_SECONDS | 300 | LRU cache TTL for catalogs | | HTTP_TIMEOUT_MS | 30000 | Request timeout | | MAX_RESPONSE_CHARS | 60000 | Per-response context-budget ceiling | | MAX_DOWNLOAD_BYTES | 10000000 | Cap for files downloaded + parsed locally | | LOG_LEVEL | info | debug/info/warn/error |

Develop

npm test          # vitest
npm run typecheck
npm run lint
npm run smoke      # live test against data.gov.ua
npm run build:dxt  # build the .dxt package

The portal runs CKAN 2.7.2. DataStore (queryable rows) covers only ~0.3 % of resources, so get_dataset_data downloads + parses files locally when needed; filter_data/SQL apply to the DataStore-active minority.

License

MIT © Open Data UA Community