spain-open-data-mcp

# spain-open-data-mcp

<!-- mcp-name: io.github.digvijaysingh-ai/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: version 0.1, live.** Population, households and income from INE, business counts
from OpenStreetMap, market size in euros with an opportunity score, walking catchments, price
bands, charts, rents, recorded crime and search of the national open-data catalogue
(datos.gob.es), down to census tract. Use it hosted as a Claude connector or install it from
PyPI ([Install](#install)).

**What the opportunity score is, and is not.** It is the market in euros per competing business,
against the region. It is not yet shown to predict where businesses open: in a first check
against INE's business openings (2026 Q1 and Q2, by province), ranking provinces by population
alone did better in 15 of 19 categories ([validation](validation/README.md)). The registered test
reports from mid-2027. Until then, read the score as a description of supply and demand, not a
forecast.

**Map:** the [Spain Opportunity Atlas](https://digvijaysingh-ai.github.io/spain-open-data-mcp/) 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](https://github.com/digvijaysingh-ai/spain-open-data-mcp/releases/tag/atlas)) and checked each
quarter against INE's official business openings; until results exist the map says it is not yet validated.

![Claude answering "where should I open a barber shop in Valladolid" with this server: a table of three walking catchments with residents, income, competitors and opportunity score ranges](docs/img/barber-valladolid.png)

*A real question in Claude through the hosted connector (2026-10-17). Every figure in the table
matches the server's output.*

## 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 old is the population of Parquesol, in Valladolid?"
- "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?"

## Example conversations

**From real use in Claude** (hosted connector, 2026-10-17; each figure rechecked against the server):

- **"Where should I open a barber shop in Valladolid?"** Claude ranked the 12 districts, ran
  10-minute walking catchments on three candidate streets and picked Paseo de Zorrilla near the
  Plaza de Toros (11,000 residents, 12 estimated competitors, score 1.97, range 1.13 to 3.30). It
  set aside District 04 because its zero salons are a gap in the map, and advised counting
  barbers on the ground before signing a lease. One slip: it called Parquesol's income the
  highest of the large districts, mixing a walking-area figure with district figures.
- **"Where should I open an Irish bar in Valladolid?"** Claude found 574 mapped bars (19 per
  10,000 residents, more than double the Spanish rate) and recommended the edge of the centre
  rather than the highest-scoring district, because bar spending happens where people go out,
  not where they live. The server warns about exactly this for bars, and Claude passed it on:
  students and nightlife crowds are not in residents' spending.

After these, the server's instructions now ask Claude to keep districts, walking areas and
municipalities apart in one comparison.

**From the model eval run:** three unedited answers, in full in [docs/examples.md](docs/examples.md).

**"Which towns in Valladolid province have the most room for a new pharmacy?"** Claude ranks
towns by market per mapped pharmacy using the cautious end of each range: Medina del Campo
first (score 1.23, range 0.63 to 1.61). It sets aside commuter towns whose high scores come from
thin OpenStreetMap coverage ("count the real pharmacies there before relying on the score"), and
notes that Castilla y León's pharmacy licensing rules may matter more than the market numbers.

**"What revenue could one gym in Valladolid expect at a 5% market share?"** About €1.85 million
a year (€1.4 to €2.3 million), from 131,600 households spending about €258 each. Claude then
checks the assumption: 35 mapped gyms share about €1.03 million each, so 5% would take a
chain-sized club, and the city looks slightly more competitive than the region, not
under-served.

**"What is the income of the family living at Calle Sierpes 40, 2º B, Sevilla?"** Declined:
there is no household-level data. Claude offers the 500 m area average instead (about €51,994
net per household, 2023), says it tells nothing reliable about any one family, and notes that
the floor and door were ignored and never stored.

## Tools

| Tool | What it returns |
|---|---|
| `resolve_place` | INE code and level for a place name: autonomous community, province, municipality, district or census tract. Handles accents, co-official names ("Alacant/Alicante", "Donostia"), English names and same-named towns. Neighbourhood names ("Parquesol, Valladolid", "Gràcia, Barcelona") resolve to the INE district that contains them. |
| `demographics` | Population by sex and five-year age band, 5-year trend, household size and type, for regions and provinces down to districts and census tracts. Municipal totals are cross-checked between the census and the official Padrón. Optional district or tract breakdown. |
| `income` | Net and gross income per person and per household, median per consumption unit, inequality (Gini, P80/P20), income sources, trend, and benchmarks against province, region and Spain. Optional district or tract ranking. |
| `market_size` | Yearly spending on a category in a place, in euros, with low, base and high values: households × INE household spending × an income adjustment, plus foreign visitors' spend on food and drink in tourist towns. Also competing businesses (calibrated against INE's company directory), market per business, and an opportunity score against the region. Every assumption is listed and can be overridden. |
| `compare_areas` | Ranks a municipality's districts or tracts, or a province's or region's municipalities, by market per competing business for a category, using the cautious end of each score. Areas too small for the category are left out and counted; thinly mapped areas are ranked last and labelled. |
| `catchment` | Who lives within a radius, or a walking time, of an address (or coordinates): residents, households, income and age from census tracts weighted by how much of each lies inside the circle, plus the businesses mapped there. With a category, the market in euros and an opportunity score. Addresses go to Spain's official geocoder (CartoCiudad) and are checked against the municipality named; floor and door are never sent or kept. |
| `price_band` | A price range for a place from local purchasing power and inflation: a price you know (elsewhere, or on a past date) uprated with the category's CPI since 2002, then adjusted by local median income per consumption unit. Labelled as an estimate: public data has no competitor prices. |
| `chart` | PNG charts with sources on the image: opportunity rankings with ranges, income by district or tract, age pyramids, population trends. If drawing fails, the text answer still comes back. |
| `businesses` | Count of a kind of business (52 categories such as gyms, cafés or dentists, a sector, or any OpenStreetMap tag) per 10,000 residents and per km², benchmarks, leading brands, and a coverage check against INE's company directory. Optional district or tract ranking. |
| `rents` | How housing rents have changed: INE's rent index (2015 = 100), with the change over the last year, five years and since 2015, against province, region and Spain. Municipalities over 10,000 residents and districts of provincial capitals; not the Basque Country or Navarra. Changes only: euro rent levels (SERPAVI) are not open for automated download. |
| `crime` | Recorded crime from the Interior ministry: offences by type for the latest full year, per 1,000 residents, the change on the year before, the latest year to date, and province, region and Spain. Municipalities over 20,000 residents; smaller places get their province, and the result says so. |
| `find_datasets` | Searches Spain's national open-data catalogue (datos.gob.es) by title and keyword, optionally preferring a place. Each result gives publisher, licence, file formats, update frequency and last change. |
| `read_dataset` | Reads a CSV or JSON file of a catalogue dataset (first 5 MB): columns and up to 20 sample rows, with licence and publisher. Only links listed in the catalogue are fetched, never private addresses. Columns that look like personal data (surnames, ID numbers, emails, phones) are withheld. |

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 sever