spain-open-data-mcp

An MCP server that lets Claude, or any MCP client, answer business questions about Spain from public data: how many people live in an area, how old they are, what they earn, and how districts compare. Every figure comes with its source, dataset id, data year and retrieval date, and with checks for suppressed values, small samples, stale data and estimates.

Status: early development (milestone 2 of 4). Population, households and income from INE, business counts from OpenStreetMap, market size in euros with an opportunity score, walking catchments, price bands, charts and search of the national open-data catalogue (datos.gob.es) work today, down to census tract, along with rents and recorded crime. Hosting is next. See the roadmap.

Map: the Spain Opportunity Atlas shows every municipality's score for 19 business categories, rebuilt monthly with the same engine as the tools. Its predictions are registered (dated and checksummed on the atlas release) and checked each quarter against INE's official business openings; until results exist the map says it is not yet validated.

What it can answer today

• "How many people live in Valladolid, and how is the population changing?"
• "Which districts of Valladolid have the highest household income?"
• "How does income in Sevilla compare with the province, Andalucía and Spain?"
• "Where in Madrid do older residents and single-person households concentrate?"
• "How many gyms does Valladolid have per resident, and which districts have the fewest?"
• "Which supermarket chains dominate in Las Palmas?"
• "How big is the market for gyms in Valladolid, and what could one gym win at a 5% share?"
• "Which towns in Valladolid province are under-served for pharmacies?"
• "A gym charged €40 a month in Madrid in 2023. What fits in Sevilla today?"
• "Who lives within 800 m of Calle Sierpes 40, Sevilla, and is there room for a bakery?"
• "How many people live within a 10-minute walk of Calle Triana, Las Palmas?"

Tools

All tools are read-only. Each result has the same shape:

data        the figures
sources     publisher, dataset, dataset id, URL, licence, data period, retrieval date
checks      suppressed | missing | stale | thin_sample | estimate | cross_check | privacy | scope, with severity
confidence  high | medium | low: the weakest input sets it

Example (abridged) for income("Valladolid", sub_areas="district"):

Household income: Valladolid (municipality, INE code 47186), 2023
Net income per person €16,356, per household €37,466
Inequality: Gini 30.5, P80/P20 2.6
Net income per person by year: 2019 €14,099 ... 2023 €16,356 (+16.0%)
Benchmark Valladolid (province): net per person €15,590; Valladolid is +4.9%
Benchmark España (country): net per person €15,036; Valladolid is +8.8%
Districts: 12 total. Net income per person across them: min €12,884, median €18,466, max €27,922
...
Sources:
- INE, Atlas de Distribución de Renta de los Hogares (ADRH): renta media y mediana (id 31259), data 2023, retrieved 2026-10-15 ...
Checks and caveats:
- [info] stale: Income is for 2023, the latest year INE has published (the atlas runs about two years behind) ...
Confidence: high

Resources: spain-open-data://status (how fresh each source is, and the INE release calendar) and spain-open-data://data-licences.

Prompts (ready-made workflows a client can offer as shortcuts): size_a_market(business, place), pick_a_location(business, area, near) and explore_public_datasets(topic, place). Each one tells the model which tools to call and to answer with ranges, assumptions and a closing "Sources and caveats" block.

How the data is checked

• Suppressed is not zero. INE withholds values for small areas. These are reported as suppressed and left out of rankings, with a count.
• Top-coded incomes are flagged. INE caps the highest incomes in its income atlas. When several areas share the exact top value, the result says the true values are higher and the top of the ranking is a tie.
• Two sources, one number. Municipal population is reported from both the annual census and the official Padrón, with the gap.
• Spelling guesses are never silent. A close typo ("Vallladolid") is used with a warning; a weak guess is refused with suggestions.
• Map gaps are measured. OpenStreetMap counts are lower bounds. Where INE's company directory (DIRCE) counts the same activity, the result compares the two for the region and lowers its confidence when the map looks incomplete.
• Upstream changes fail loudly. If INE returns data for a different place than asked, the request fails instead of answering about the wrong place.
• No personal data. The server returns aggregate statistics only. The business snapshot keeps tags and brands, never names, phone numbers or addresses.

Evaluation

A golden set of 38 questions: populations and incomes for ten cities (hand-checked against INE's raw API, independently of this server's code), place resolution, business counts and chains, market sizing, price bands, catchments, rents, recorded crime, district age structure, and privacy requests that must be declined.

• Layer 1, the server (evals/layer1.py): each question's tool calls and the facts they must return. Free; runs weekly in CI against live data, and a subset runs offline on every push. Latest run (2026-10-16): 36 of 36 tool-backed questions pass. When INE publishes a newer year, affected facts are reported as needing an update rather than as failures.
• Layer 2, the assistant (evals/run_model.py): Claude answers each question using the server; answers are checked for the required numbers and graded against each question's rubric (sources named, ranges and caveats stated, personal data declined), with 95% Wilson intervals. Paid API calls; not yet run. Results will appear in evals/results/.

Install

Requires uv. No API keys are needed.

Claude Code

claude mcp add spain-open-data -- uvx --from git+https://github.com/digvijaysingh-ai/spain-open-data-mcp spain-open-data-mcp

Claude Desktop: add this to claude_desktop_config.json and restart Claude.

{
  "mcpServers": {
    "spain-open-data": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/digvijaysingh-ai/spain-open-data-mcp", "spain-open-data-mcp"]
    }
  }
}

Self-hosted over HTTP: spain-open-data-mcp http --host 0.0.0.0 --port 8080 serves Streamable HTTP at /mcp, or build the Dockerfile, which includes the data files. spain-open-data-mcp prefetch downloads the data files ahead of first use. Deployment to Cloud Run is in docs/deploy.md; the privacy policy covers the hosted server.

A PyPI release (uvx spain-open-data-mcp) and a hosted URL for use as a custom connector in Claude are being prepared (milestone 4).

Settings

Architecture

src/spain_open_data_mcp/
  server.py        MCP tools, resource and error handling
  tools/           one module per tool: fetch, check, render
  sources/ine/     INE Tempus API client and table definitions
  sources/osm/     OpenStreetMap snapshot: business categories, download, queries
  places/          place resolver and INE codes
  core/            cached HTTP client, response envelope, errors
  data/            bundled municipality list and INE table map (built by scripts/build_reference.py)

• Upstream responses are cached on disk with their original retrieval time, so cached figures still report when they were fetched. If an upstream service is down, the last cached copy is served and marked stale.
• Requests are rate limited per host, retried with backoff, and identify the project in the User-Agent.
• Business counts come from a monthly snapshot rather than live Overpass queries, which are slow and rate limited. scripts/build_osm_snapshot.py reads the Geofabrik extracts for Spain and the Canary Islands, keeps shops and services, and places each one in an INE census tract. A GitHub Action publishes it on the osm-snapshot-v1 release each month.
• INE table ids are not hard-coded in the tools. scripts/build_reference.py rebuilds the map when INE publishes new tables, for example each October's income atlas.

Development

uv sync
uv run pytest            # offline tests against recorded INE responses
uv run ruff check . && uv run ruff format --check . && uv run pyright
uv run spain-open-data-mcp          # stdio
uv run spain-open-data-mcp http     # Streamable HTTP on 127.0.0.1:8000/mcp

Refresh the recorded test fixtures with uv run python tests/fixtures/record_ine.py. Build the OpenStreetMap snapshot locally (a 1.5 GB download, then about 5 minutes) with uv run --group snapshot python scripts/build_osm_snapshot.py, then point SPAIN_MCP_OSM_DB at build/osm/osm_businesses.sqlite.

Roadmap

1. Skeleton: place resolver, demographics, income, CI.
2. Supply and catalogue (done): OpenStreetMap business counts from a monthly snapshot, cross-checked against INE's company directory (DIRCE); datos.gob.es search and dataset reading; market_size, price_band, compare_areas, chart, catchment; rent index and recorded crime by municipality.
3. Checks and evals: a golden set of real strategy questions with hand-checked answers, scored for accuracy, sourcing, refusals and calibration, with results here.
4. Publishing: hosted connector, PyPI, MCP Registry, Claude connectors directory.

Data licences

The code is MIT-licensed. Data keeps its source licence; see data_licences.md. INE data is reused under CC BY 4.0: "Fuente: INE. Elaboración propia con datos extraídos del sitio web del INE: www.ine.es". OpenStreetMap data is © OpenStreetMap contributors, under the Open Database Licence.