DataPrem MCP Server

A Model Context Protocol (MCP) server that exposes Spanish public-data sources to AI agents (Claude Desktop, Cursor, ChatGPT, …).

It is a thin client of the DataPrem REST API: each MCP tool maps to an HTTPS call against api.dataprem.com using your API key.

Requires the MCP Python SDK 2.x (mcp>=2.0.0,<3).

Tool status (0.4.0)

Every tool answers with real data. The subsidies one carries its attribution in meta.source: its terms of reuse ask for the origin to be named wherever the data is shown.

Getting an API key

Every tool requires a Bearer token from api.dataprem.com:

1. Request access by email to info@dataprem.com, describing your use case.
2. You will receive a token prefixed dpa_… along with the API URL.
3. Configure it in your MCP client (next section).

Installation

Requires Python 3.11+.

# Via PyPI (recommended for MCP clients)
uvx dataprem-mcp

# Or local install for development
pip install -e ".[dev]"

Claude Desktop configuration

Edit claude_desktop_config.json (Mac: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "dataprem": {
      "command": "uvx",
      "args": ["dataprem-mcp"],
      "env": {
        "DATAPREM_API_KEY": "dpa_YOUR_TOKEN_HERE",
        "DATAPREM_API_URL": "https://api.dataprem.com"
      }
    }
  }
}

Restart Claude Desktop. The four tools should show up as available to the model.

Server-side HTTP transport

For clients that cannot spawn the server as a subprocess (e.g. a multi-request web app) there is a streamable-http transport that runs the server as a long-lived process listening for JSON-RPC over HTTP.

# Without Docker
python -m dataprem_mcp --transport streamable-http --host 0.0.0.0 --port 8080

# With Docker
docker compose up dataprem_mcp     # local image build; exposed only on the internal network

The MCP endpoint is /mcp (no trailing slash). The standard handshake (initialize → tools/list → tools/call) works with Content-Type: application/json and Accept: application/json, text/event-stream. Each conversation receives an mcp-session-id that the client must echo back on subsequent requests.

# Example: initialize handshake
curl -sL -X POST http://127.0.0.1:8080/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-03-26",
      "clientInfo": {"name": "smoke", "version": "1"},
      "capabilities": {}
    }
  }' -i

By default the compose service does not publish the port to the host: place it on a Docker network shared with your client and reach it as http://dataprem_mcp:8080/mcp.

Alternative configuration (local development)

{
  "mcpServers": {
    "dataprem-dev": {
      "command": "python",
      "args": ["-m", "dataprem_mcp"],
      "cwd": "/path/to/dataprem-mcp",
      "env": {
        "DATAPREM_API_KEY": "dpa_dev_token",
        "DATAPREM_API_URL": "http://localhost:8000"
      }
    }
  }
}

Environment variables

Tools — reference

dataprem_catastro_lookup ✅ Live

Looks up cadastral data for a property. Two modes are supported:

By cadastral reference:

By address:

Returns the normalised cadastral record (class, use, surfaces, year of construction, address with INE codes, breakdown of constructions by floor and use). Does not expose the owner for LOPD/GDPR reasons.

dataprem_borme_search

dataprem_subsidies_search

Every parameter is optional on its own, but at least one is required.

dataprem_tenders_search

Every parameter is optional on its own, but at least one is required: searching for everything is not a search.

buyer is who put the contract out; company is who won it — the one no other source answers: what a given firm has been awarded. cpv widens or narrows by how much of the code you give — 45 is every construction contract, 45210000 one kind of building.

Response shape

Every tool returns a dict marking success or failure with ok:

{ "ok": true, "data": { ... cadastral record ... } }

{ "ok": false, "error": "unauthorized", "message": "API key invalid or revoked..." }

A search also carries meta, which says what the results alone do not: that there are more of them, and which years hold them, so narrowing is not guesswork.

{ "ok": true,
  "meta": { "count": 25, "has_more": true, "years": [2024, 2025, 2026] },
  "data": [ ... ] }

A value the API refuses comes back with the ones it accepts, rather than as a bare failure:

{ "ok": false, "error": "invalid_request", "message": "Unknown tender status \"ABIERTA\".",
  "statuses": ["PRE", "PUB", "EV", "ADJ", "RES", "ANUL"] }

A search with nothing to narrow by is refused, and the answer says what it takes:

{ "ok": false, "error": "invalid_request",
  "message": "A subsidy search needs something to narrow by: text, a beneficiary, a granting body, a level, an amount or a date.",
  "levels": ["ESTADO", "AUTONOMICA", "LOCAL", "OTRA"] }

Error codes:

Development

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Start the installed console script over stdio and list its tools,
# the same way a desktop client does. The suite alone cannot catch a
# package that imports fine from the source tree but not once installed.
python scripts/smoke_stdio.py

# Run the server with a local API key
DATAPREM_API_KEY=dpa_xxx DATAPREM_API_URL=http://localhost python -m dataprem_mcp

Releasing

Publishing runs from CI through PyPI trusted publishing, so no token lives on anyone's machine:

# bump the version in pyproject.toml and add the CHANGELOG entry, then
git tag 0.3.4
git push origin 0.3.4

The release workflow builds, checks the artifact, installs the wheel, starts it over stdio, refuses to continue if the tag disagrees with the built version, and only then publishes.

License

MIT