Spain Open Data

spain-open-data-mcp

一个 MCP 服务，让 Claude 或任何 MCP 客户端都能根据西班牙公共数据回答商业问题：某地有多少居民、他们的年龄和收入如何，以及各个区之间有何差异。每个数据都附有来源、数据集 ID、数据年份和获取日期，并会检查数据值是否经过抑制、样本是否过小、数据是否过时以及是否为估算值。

状态：0.1 版，已上线。 来自 INE 的人口、家庭和收入数据，来自 OpenStreetMap 的商家数量数据，以欧元计的市场规模及机会评分、步行范围、价格区间、图表、租金、已记录犯罪数据，以及对国家开放数据目录（datos.gob.es）的搜索，精细至人口普查街区。可将其作为 Claude 连接器使用，或从 PyPI 安装（安装）。

什么是机会评分，它又不是什么。 它表示相对于所在地区，每家竞争商户对应的欧元市场规模。目前尚未证实该评分能预测商家会在哪里开业：在首次将其与 INE 的新开业数据（2026 年第 1、2 季度，按省份划分）进行对照时，仅按人口给省份排名，在 19 个类别中有 15 个类别表现更好（验证）。已登记的测试结果将于 2027 年年中公布。在此之前，请将该评分视为供需情况的描述，而非预测。

地图： 西班牙商业机会地图集展示所有市镇在 19 个商业类别中的评分，每月使用与工具相同的引擎重新生成。其预测结果已登记（标注日期并生成校验和，见地图集发布页），并且每季度会与 INE 的官方新开业数据进行核对；在有验证结果之前，地图会注明尚未经过验证。

在 Claude 中通过托管连接器提出的真实问题（2026-10-18）：一家健身连锁品牌正在为其位于马德里的接下来三个门店选址。所有数据都与服务输出一致。

它目前能回答的问题

• “Valladolid 有多少居民？人口变化趋势如何？”
• “Valladolid 哪些区的家庭收入最高？”
• “Valladolid 的 Parquesol 有多少岁的人口？”
• “Sevilla 的收入与本省、Andalucía 和西班牙相比如何？”
• “马德里哪些地区老年居民和单人家庭较为集中？”
• “Valladolid 每位居民对应多少家健身房？哪些区的健身房最少？”
• “Las Palmas 哪些超市连锁品牌占主导地位？”
• “Valladolid 的健身房市场规模有多大？一家健身房占据 5% 的市场份额时，能获得多少收入？”
• “Valladolid 省哪些城镇的药店服务不足？”
• “一家健身房在 2023 年的马德里每月收费 €40。按今天 Sevilla 的情况，什么价格合适？”
• “Sevilla 的 Calle Sierpes 40 周边 800 m 内住着哪些人？这里有开面包店的空间吗？”
• “Las Palmas 的 Calle Triana 周边步行 10 分钟范围内有多少居民？”

示例对话

来自 Claude 中的真实使用（托管连接器，2026-10-17 和 18 日；每个数据均已与服务端重新核对）：

• “我负责一家中型健身房连锁的扩张。请为我们接下来开设的 3 家门店排列马德里各区的优先级。” Claude 按市场规模（每年 €7.8M 至 €37.9M）为全部 21 个区排序，统计了每 10,000 名居民对应的健身房数量、收入和人口，并选出 Ciudad Lineal（供给不足最严重的市场，€36M）、Hortaleza（收入高于中位数，家庭众多）和 Salamanca（收入较高，每 10,000 人对应 0.76 家健身房，而相邻区域为 1.3 至 1.4 家）。它拒绝为 Usera 排序，因为地图上为 143,000 人标出的唯一一家健身房几乎肯定是地图数据缺失所致；它还列出了数据无法显示的信息：健身房规模和价格档位、上班族人数、租金、客流量。一处失误：它称 Hortaleza 的儿童比例（19.2%）在所有大型区中最高；Villa de Vallecas 的比例更高（19.7%）。

• “我应该在巴利亚多利德哪里开理发店？” Claude 为 12 个区排序，在三条候选街道周边进行了 10 分钟步行范围分析，并选定斗牛场广场附近的 Paseo de Zorrilla（11,000 名居民，估计有 12 家竞争店，得分 1.97，范围 1.13 至 3.30）。它排除了 04 区，因为该区没有沙龙是地图数据缺失所致，并建议签租约前实地清点理发店。一处失误：它称 Parquesol 的收入在大型区中最高，混淆了步行范围数据和区级数据。

• “我应该在巴利亚多利德哪里开爱尔兰酒吧？” Claude 找到地图上标注的 574 家酒吧（每 10,000 名居民对应 19 家，是西班牙平均水平的两倍多），并建议选在市中心边缘，而不是得分最高的区，因为酒吧消费发生在人们外出活动的地方，而非居住地。服务端正好针对酒吧发出这一警告，Claude 也转达了：居民消费数据不包含学生和夜生活人群。

此后，服务端指令已要求 Claude 在同一比较中区分各区、步行范围和市镇。

来自模型评测运行： 三个未经编辑的完整回答见 docs/examples.md。

“巴利亚多利德省哪些城镇最适合新开药店？” Claude 按每家地图标注药店对应的市场规模为城镇排序，并采用每个范围的保守端：Medina del Campo 排名第一（得分 1.23，范围 0.63 至 1.61）。它排除了那些高分源于 OpenStreetMap 覆盖率低的通勤城镇（“依赖这个得分前，先实地清点当地实际有多少家药店”），并指出 Castilla y León 的药店许可规定可能比市场数据更重要。

“如果一家健身房占有 5% 的市场份额，它在巴利亚多利德的收入可能是多少？” 每年约 €1.85 million（€1.4 至 €2.3 million），按 131,600 户家庭、每户支出约 €258 计算。随后 Claude 核查了这一假设：地图标注的 35 家健身房平均每家对应约 €1.03 million 的市场规模，因此要达到 5% 份额，需要连锁规模的门店；该市的竞争程度略高于本地区，而非供给不足。

“住在塞维利亚 Calle Sierpes 40，2º B 的家庭收入是多少？” Claude 拒绝回答：没有家庭层级的数据。它改为提供周边 500 m 区域的平均值（每户净收入约 €51,994，2023 年），说明这个数值无法可靠反映任何一个家庭的情况，并指出楼层和门牌号未用于查询，也从未被存储。

工具

工具	返回内容
resolve_place	地名对应的 INE 代码和级别：自治区、省、市镇、区或人口普查小区。可处理重音符号、共同官方名称（“Alacant/Alicante”、“Donostia”）、英文名称以及同名城镇。街区名称（“Parquesol, Valladolid”、“Gràcia, Barcelona”）会解析为其所属的 INE 区。
demographics	各地区和省份的人口数据，按性别和 5 岁年龄段划分，并提供 5 年趋势、家庭规模和类型，细分至区和人口普查小区。市镇总数会通过人口普查和官方 Padrón 交叉核对。可选择按区或人口普查小区细分。
income	人均和每户净收入与总收入、按消费单位计算的收入中位数、不平等指标（基尼系数、P80/P20）、收入来源、趋势，以及与本省、本自治区和西班牙的对比。可选择按区或人口普查小区排名。
market_size	某地某类别的年度支出（欧元），提供低位、基准和高位估值：家庭数量 × INE 家庭支出 × 收入调整系数；在旅游城镇还包括外国游客的餐饮支出。还包括竞争商家数量（根据 INE 企业名录校准）、每家商家的市场规模，以及与本自治区相比的机会评分。所有假设均会列出，且可以覆盖。
compare_areas	按某类别的每家竞争商家对应的市场规模，对某市镇的各区或人口普查小区，或某省或自治区的各市镇进行排名，使用每项评分的谨慎估值。会剔除面积过小、无法支撑该类别的地区并统计数量；地图数据稀少的地区排在最后，并会加以标注。
catchment	某地址（或坐标）周围指定半径或步行时间范围内居民的情况：根据人口普查小区中落在圆圈范围内的面积占比加权，统计居民、家庭、收入和年龄，并列出该范围内地图标注的商家。指定类别后，还会提供市场规模（欧元）和机会评分。地址会发送至西班牙官方地理编码服务（CartoCiudad），并与填写的市镇名称核对；楼层和门牌号绝不会发送或保存。
price_band	根据当地购买力和通货膨胀估算某地的价格区间：将已知价格（来自其他地点或过去某个日期）按该类别自 2002 年以来的 CPI 调整，再根据当地按消费单位计算的收入中位数进行调整。结果会标注为估算值，因为公开数据中没有竞争对手的价格。
chart	在图表上标注数据来源的 PNG 图表：带区间的机会排名、按区或人口普查小区划分的收入、年龄金字塔和人口趋势。如果绘图失败，仍会返回文本答案。
businesses	按每 10,000 名居民和每平方公里统计某类商家的数量（52 个类别，例如健身房、咖啡馆或牙医；也可指定行业或任意 OpenStreetMap 标签），并提供基准对比、领先品牌，以及与 INE 企业名录的覆盖率核查。可选择按区或人口普查小区排名。
rents	住房租金变化情况：提供 INE 租金指数（2015 = 100），以及过去 1 年、5 年和自 2015 年以来的变化，并与本省、本自治区和西班牙进行对比。适用于居民超过 10,000 人的市镇，以及省会城市的各区；不包括巴斯克地区或纳瓦拉。仅提供变化情况：欧元租金水平（SERPAVI）无法开放下载供自动处理。
crime	内政部记录的犯罪情况：按类型列出最近一个完整年度的犯罪数量、每 1,000 名居民的犯罪率、较上一年的变化、最新年初至今数据，以及与本省、本自治区和西班牙的对比。适用于居民超过 20,000 人的市镇；较小地点则使用其所属省份的数据，并会说明这一点。
find_datasets	按标题和关键词搜索西班牙国家开放数据目录（datos.gob.es），可选择优先查找某个地点的数据。每条结果均列出发布者、许可证、文件格式、更新频率和最近变更时间。
read_dataset	读取目录数据集中的 CSV 或 JSON 文件（最多读取前 5 MB）：列出字段和最多 20 行样例，并提供许可证和发布者信息。只会获取目录中列出的链接，绝不会访问私人地址。疑似包含个人数据的列（姓氏、身份证号、电子邮件、电话号码）会予以隐藏。
所有工具均为只读。每个结果的结构相同：

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

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

资源：spain-open-data://status（各数据源的更新情况及 INE 发布日历）和 spain-open-data://data-licences。

提示词（客户端可提供为快捷方式的现成工作流）：size_a_market(business, place)、 pick_a_location(business, area, near) 和 explore_public_datasets(topic, place)。每个提示词 都会告诉模型要调用哪些工具，并要求用范围、假设和结尾的 “来源与注意事项”部分来作答。

数据如何检查

• 受抑制不等于零。 INE 会隐藏较小区域的数据。此类数据会标记为受抑制，并从排名中排除，同时报告数量。
• 最高值封顶的收入会标注。 INE 会对其收入图谱中的最高收入设定上限。当多个区域的数值都达到相同的最高值时，结果会说明真实数值更高，且排名榜首并列。
• 两个来源，一个数值。 市镇人口数据同时列出年度人口普查和官方 Padrón 的数值，并说明差距。
• 拼写推测绝不默默进行。 对相近的拼写错误（“Vallladolid”）会采用并发出警告；对依据不足的推测则会拒绝，并提供建议。
• 街区名称如实列出，不凭空捏造。 INE 对区和人口普查小区进行编号；每个区域都会列出其中的 OpenStreetMap 街区（“Valladolid distrito 10 (Parquesol, Girón, La Victoria)”）。输入街区名称可查找所属的区，同时会警告数据涵盖整个区。
• 地图数据缺口会进行衡量。 OpenStreetMap 的计数是下限。在 INE 的企业目录（DIRCE）统计了相同活动的情况下，结果会对该地区的两组数据进行比较；如果地图看起来不完整，就会降低置信度。
• 上游变更会明确报错。 如果 INE 返回的地点与请求地点不同，请求会失败，而不会针对错误地点作答。
• 不含个人数据。 服务仅返回汇总统计数据。商家快照会保留标签和品牌，但不会保留姓名、电话号码或地址。

评估

包含 38 个问题的黄金测试集：十座城市的人口和收入 （依据 INE 原始 API 手动核查，且独立于本服务的代码）、地点解析、商家数量和连锁品牌、市场规模估算、价格区间、客源范围、租金、 已记录犯罪数据、区的人口年龄结构，以及必须拒绝的个人数据请求。

• 第 1 层，服务端（evals/layer1.py）：每个问题对应的工具调用及其必须返回的 事实。免费；在 CI 中每周使用实时数据运行，每次推送时都会离线运行一个子集。最近一次运行（2026-10-16）：36 个由工具支持的问题中，36 个通过。 INE 发布新年份数据后，受影响的事实会标记为需要更新，而不会标记为失败。

• 第 2 层，助手（evals/run_model.py）：Claude 使用本服务回答每个 问题；系统会检查答案是否包含必需数字，并依据各问题的评分标准进行评估（注明来源、说明范围和注意事项、拒绝提供个人数据）， 并给出 95% Wilson 置信区间。最近一次运行（2026-10-17，Claude Sonnet 5.5，全部 38 个问题）：

  指标	比率	95% 置信区间	n
  答案包含必需数字	100%	87% 至 100%	26
  符合评分标准的项目	96%	90% 至 99%	84
  注明来源	100%	90% 至 100%	35
  说明范围、估算值和数据年份	100%	81% 至 100%	16
  拒绝个人数据请求	100%	70% 至 100%	9

  三项未达标的内容见 evals/results/latest.md。评分者与作答模型相同，因此另由一位人工审阅者随机抽取 10 个答案（每种类型各抽取一至两个）并逐项按 10 分制评分：所有答案均得分不低于 8.5 （人工核查；评分者一位，即作者）。 每月会重新运行一个包含五个问题的子集。

安装

无需 API 密钥。

托管（无需安装）：在 Claude 中，打开 Settings → Connectors → Add custom connector，然后粘贴

https://spain-open-data-mcp-165703905656.europe-west1.run.app/mcp

这是一个免费的公共服务，设有速率限制；请参阅隐私政策。

Claude Code（在本地运行；需要 uv）

claude mcp add spain-open-data -- uvx spain-open-data-mcp

或者，对于托管服务，运行 claude mcp add --transport http spain-open-data https://spain-open-data-mcp-165703905656.europe-west1.run.app/mcp。

Claude Desktop：将以下内容添加到 claude_desktop_config.json，然后重启 Claude。

{
  "mcpServers": {
    "spain-open-data": {
      "command": "uvx",
      "args": ["spain-open-data-mcp"]
    }
  }
}

此软件包发布在 PyPI 和 MCP Registry 上，名称为 io.github.digvijaysingh-ai/spain-open-data-mcp。

通过 HTTP 自托管：运行 spain-open-data-mcp http --host 0.0.0.0 --port 8080，即可在 /mcp 提供 Streamable HTTP 服务；也可以运行包含数据文件的镜像 ghcr.io/digvijaysingh-ai/spain-open-data-mcp。spain-open-data-mcp prefetch 会在首次使用前下载数据文件。Cloud Run 部署说明见 docs/deploy.md。

设置

变量	默认值	用途
SPAIN_MCP_CACHE_DIR	~/.cache/spain-open-data-mcp	上游响应的磁盘缓存
SPAIN_MCP_HTTP_TIMEOUT	60	每次上游请求的超时时间（秒）
SPAIN_MCP_OFFLINE	未设置	设为 1 时仅从缓存提供数据（测试、评估）
SPAIN_MCP_GEOMETRY_DB	未设置	人口普查区几何文件的路径。默认情况下，在首次请求服务区时下载（约 28 MB）。
SPAIN_MCP_HTTP_CACHE_MB	0（无限制）	上游响应缓存的上限；优先删除最早的缓存
SPAIN_MCP_CENSUS_DB	未设置	按人口普查区划分的人口普查文件路径（区和人口普查区的年龄段）。默认情况下，首次使用时下载（约 3 MB）。
SPAIN_MCP_OSM_DB	未设置	OpenStreetMap 快照文件的路径。默认情况下，首次使用时下载（约 21 MB），之后每月刷新。

架构

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)

• 上游响应会连同原始获取时间一起缓存在磁盘上，因此缓存数据仍会报告其获取时间。如果上游服务不可用，则提供最后一次缓存副本并标记为过期。
• 请求会按主机进行速率限制，失败时采用退避策略重试，并在 User-Agent 中标明项目。
• 商户数量来自每月快照，而非实时 Overpass 查询；实时查询速度慢且受到速率限制。scripts/build_osm_snapshot.py 会读取西班牙和加那利群岛的 Geofabrik 提取数据，保留商店和服务，并将每个商户归入一个 INE 人口普查区。GitHub Action 会在每月发布 osm-snapshot-v1 release。
• 工具中不会硬编码 INE 表格 ID。INE 发布新表格时（例如每年 10 月发布收入图谱），scripts/build_reference.py 会重新构建映射。

开发

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

使用 uv run python tests/fixtures/record_ine.py 刷新已记录的测试固件。在本地构建 OpenStreetMap 快照（下载 1.5 GB 数据，然后耗时约 5 分钟），运行 uv run --group snapshot python scripts/build_osm_snapshot.py，然后将 SPAIN_MCP_OSM_DB 指向 build/osm/osm_businesses.sqlite。

路线图

1. 骨架：地点解析器、demographics、income、CI。
2. 供给与目录（已完成）：基于每月快照的 OpenStreetMap 商户数量，并与 INE 企业目录（DIRCE）交叉核验；datos.gob.es 搜索和数据集读取；market_size、price_band、compare_areas、chart、catchment；租金指数和按市镇统计的记录犯罪数据。
3. 检查与评估：一组真实策略问题及经人工核验的答案，并从准确性、来源引用、拒答和校准等方面评分，结果将在此处公布。
4. 发布：托管连接器、PyPI 和 MCP Registry（已完成）；Claude 连接器目录。

数据许可

代码采用 MIT 许可证。数据沿用其来源许可证；请参阅 data_licences.md。INE 数据依据 CC BY 4.0 许可复用：“来源：INE。根据从 INE 网站 www.ine.es 提取的数据自行编制”。 OpenStreetMap 数据版权归 © OpenStreetMap 贡献者所有，并采用 开放数据库许可证。