使用说明

西班牙公共数据MCP

用于查询西班牙政府开放数据API的MCP服务器。

概述

西班牙公共数据MCP提供LLM友好的工具，用于实时查询西班牙政府数据：

BDNS -国家赠款数据库（赠款和补贴）
京东方 -官方公报（综合立法）
BORME -公司注册公报（公司法）
INE -国家统计局（官方统计）
数据.gob.es -国家开放数据目录（40000多个数据集）

架构： 实时查询官方API。不需要数据库。

总计： 26个MCP工具|211个测试|53%+覆盖率

安装

# Clone repository
git clone https://github.com/mjgmario/spanish-public-info-radar-mcp.git
cd spanish-public-data-mcp

# Install with uv (recommended)
uv sync

# For development
uv sync --extra dev

快速开始

选项1：直接运行（开发/测试）

# Install dependencies
uv sync

# Run MCP server (HTTP/SSE mode)
uv run python -m public_radar

# Or on a specific port
uv run python -m public_radar --port 9000

# Or in stdio mode (for Claude Desktop)
uv run python -m public_radar --stdio

选项2：使用Docker

# Build and run
docker-compose up -d

# View logs
docker-compose logs -f

# Stop
docker-compose down

验证它是否正常工作

# Health check (HTTP mode)
curl http://localhost:8080/health

# Should return: {"status":"healthy","service":"spanish-public-data-mcp"}

Claude桌面集成

步骤1：找到您的配置文件

Claude Desktop配置文件位于：

窗户： %APPDATA%\Claude\claude_desktop_config.json
macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
Linux： ~/.config/Claude/claude_desktop_config.json

步骤2：添加MCP服务器配置

打开配置文件并添加以下内容：

{
  "mcpServers": {
    "spanish-public-data": {
      "command": "uv",
      "args": ["run", "python", "-m", "public_radar", "--stdio"],
      "cwd": "C:\\Users\\YOUR_USER\\path\\to\\spanish-public-data-mcp"
    }
  }
}

注：替换 YOUR_USER 以及您实际安装路径的路径。

步骤3：重新启动克劳德桌面

关闭并重新打开Claude Desktop以加载新的MCP服务器。

步骤4：验证连接

问克劳德：“你有什么西班牙公共数据工具？”

Claude应该提供有关26个可用工具的信息。

可用的MCP工具

BDNS（赠款）-3个工具

工具	说明
`search_grants`	按日期范围和授权机构搜索授权呼叫
`search_grant_awards`	按日期范围和受益人NIF搜索已授予的补助金
`get_grant_details`	获取特定授权电话的详细信息

英国央行（立法）-11种工具

工具	说明
`search_legislation`	使用过滤器搜索合并法律（查询、日期、部门、法律范围、事项）
`get_legislation_details`	获取特定法律或法规的元数据（可选配法律分析）
`get_legislation_text`	获取法律的完整合并文本
`get_legislation_structure`	获取法律的结构/索引（条款、处置、附件）
`get_legislation_block`	从法律中获得特定的块（文章、处置）
`get_departments_table`	获取带有代码的政府部门列表
`get_legal_ranges_table`	获取法律规范类型列表（Ley、Real Decreto等）
`get_matters_table`	获取带有代码的主题列表
`find_related_laws`	查找与特定立法相关的法律（修改、废除、参考）
`search_recent_boe`	使用筛选器搜索过去N天的京东方出版物
`get_boe_summary`	获取特定日期的每日BOE摘要（带过滤器）

BORME（公司注册处）-1个工具

工具	说明
`get_borme_summary`	获取特定日期的每日公司注册行为

INE（统计）-6个工具

工具	说明
`get_ine_operations`	列出所有可用的统计操作（IPC、EPA、PIB等）
`get_ine_operation`	获取特定统计操作的详细信息
`get_ine_table_data`	从特定统计表中获取数据
`get_ine_series_data`	按序列码获取时间序列数据
`search_ine_tables`	在统计操作中搜索表
`get_ine_variables`	列出可用变量，可选择按操作筛选

datos.gob.es（开放数据）-4个工具

工具	说明
`search_open_data`	在国家开放数据目录中搜索数据集
`get_open_data_details`	获取特定数据集的详细信息
`list_open_data_themes`	列出可用主题/类别
`list_open_data_publishers`	列出出版机构

通用-1工具

工具	说明
`get_system_info`	获取可用数据源和工具的概述

Claude的查询示例

以下是MCP连接后您可以向Claude询问的实际示例：

赠款和补贴（BDNS）

"Find grants published in the last month"

"Search for grants related to innovation or R&D"

"What grants has the company with NIF B12345678 received?"

"Show me details of grant BDNS 123456"

立法（英国央行）

"Search for laws about renewable energy"

"What was published in the BOE today?"

"Find legislation about public subsidies from 2023"

"Show me the full text of the data protection law"

公司注册处（BORME）

"What companies were registered in Madrid today?"

"Show me the BORME summary for January 15, 2024"

"Find recent company dissolutions"

统计（INE）

"What statistical operations are available from INE?"

"Show me the latest CPI (IPC) data"

"Get unemployment statistics from the EPA survey"

"What is the current inflation rate in Spain?"

"Show me GDP growth data for the last 12 quarters"

"Find tables about population in the Census operation"

综合研究

"I want to investigate company XYZ. Check:
1. What grants have they received?
2. Any recent BORME entries about them?"

"Find all funding opportunities for renewable energy projects:
1. Current open grants
2. Relevant legislation"

"Give me an economic overview of Spain:
1. Latest unemployment rate (EPA)
2. Current inflation (IPC)
3. Recent GDP growth"

开放数据（datos.gob.es）

"Search for datasets about air quality"

"Find open data from the Madrid city council"

"What data categories are available in datos.gob.es?"

"Show me details of dataset e05068001-mapas-estrategicos-de-ruido"

刀具参数参考

搜索_咆哮

{
  "date_from": "2024-01-01",    // Optional: Start date (YYYY-MM-DD)
  "date_to": "2024-12-31",      // Optional: End date (YYYY-MM-DD)
  "granting_body": "E00003901", // Optional: Granting body code
  "limit": 20                   // Optional: Max results (1-100, default 20)
}

search_grant_awards

{
  "date_from": "2024-01-01",      // Optional: Start date
  "date_to": "2024-12-31",        // Optional: End date
  "beneficiary_nif": "B12345678", // Optional: Beneficiary NIF/CIF
  "limit": 20                     // Optional: Max results
}

get_grant_details

{
  "grant_id": "123456"  // Required: BDNS grant ID
}

搜索_立法

{
  "query": "energias renovables",  // Required: Search text
  "date_from": "2020-01-01",       // Optional: Start date
  "date_to": "2024-12-31",         // Optional: End date
  "title": "ley energia",          // Optional: Filter by title
  "department_code": "4225",       // Optional: Department code (use get_departments_table)
  "legal_range_code": "ley",       // Optional: Legal range (use get_legal_ranges_table)
  "matter_code": "170",            // Optional: Matter code (use get_matters_table)
  "include_derogated": false,      // Optional: Include repealed laws (default false)
  "offset": 0,                     // Optional: Skip results (pagination)
  "limit": 20                      // Optional: Max results (1-100)
}

get_legislation_details

{
  "legislation_id": "BOE-A-2015-10566"  // Required: BOE legislation ID
}

get_legislation_text

{
  "legislation_id": "BOE-A-2015-10566"  // Required: BOE legislation ID
}

get_legislation_structure

{
  "legislation_id": "BOE-A-2015-10566"  // Required: BOE legislation ID
}

get_legislation_block

{
  "legislation_id": "BOE-A-2015-10566", // Required: BOE legislation ID
  "block_id": "a1"                       // Required: Block ID (e.g., "a1" for article 1)
}

get_departments_table

{}  // No parameters required

get_legal_ranges_table

{}  // No parameters required

get_matters_table

{}  // No parameters required

get_boe_summary

{
  "date": "2024-01-15"  // Optional: Date (YYYY-MM-DD), defaults to today
}

get_forme_summary

{
  "date": "2024-01-15"  // Optional: Date (YYYY-MM-DD), defaults to today
}

get_ine_operations

{}  // No parameters required

get_ine_operation

{
  "operation_id": "IPC"  // Required: Operation ID or code (e.g., 'IPC', 'EPA', '25')
}

get_ine_table_data

{
  "table_id": "50902",  // Required: Table ID from INE
  "nult": 12            // Optional: Number of last periods (1-100, default 12)
}

获取_系列_数据

{
  "series_code": "IPC251856", // Required: Series code from INE
  "nult": 12                   // Optional: Number of last periods (1-100, default 12)
}

search_ine_tables

{
  "operation_id": "IPC"  // Required: Operation ID to search tables for
}

get_ine_variables

{
  "operation_id": "IPC"  // Optional: Filter variables by operation
}

搜索打开数据

{
  "query": "air quality",           // Optional: Search text
  "theme": "medio-ambiente",        // Optional: Theme code
  "publisher": "L01280796",         // Optional: Publisher ID
  "limit": 20                       // Optional: Max results (1-100)
}

get_open_data_details

{
  "dataset_id": "e05068001-mapas-estrategicos-de-ruido"  // Required: Dataset ID
}

list_open_data_themes

{}  // No parameters required

list_open_data_出版商

{
  "limit": 50  // Optional: Max results (default 50)
}

项目结构

src/public_radar/
├── common/          # HTTP client, dates, logging
├── sources/         # API clients (BDNS, BOE, INE, datos.gob.es)
│   ├── bdns.py      # BDNS client (grants)
│   ├── boe.py       # BOE client (legislation, BORME)
│   ├── ine.py       # INE client (statistics)
│   └── datos_gob.py # datos.gob.es client (open data)
├── mcp/             # MCP server and tools
│   ├── server.py    # MCP server + 26 tool handlers
│   └── logging.py   # Tool call logging (JSONL)
├── __init__.py
└── __main__.py      # CLI entry point

tests/
├── unit/            # Unit tests with mocks (168 tests)
├── integration/     # Real API tests (43 tests)
└── fixtures/        # Sample API responses

配置

环境变量

变量	描述	默认值
`MCP_HOST`	主机绑定SSE服务器	`0.0.0.0`
`MCP_PORT`	SSE服务器端口	`8080`
`MCP_LOGS_DIR`	工具调用日志目录	`./logs`
`LOG_LEVEL`	日志记录级别	`INFO`

工具调用记录

所有MCP工具调用都记录到 logs/mcp_calls_YYYY-MM-DD.jsonl:

{
  "timestamp": "2024-01-15T10:30:00Z",
  "tool": "search_grants",
  "input": {"date_from": "2024-01-01", "limit": 10},
  "output_summary": {"count": 10, "first_title": "..."},
  "duration_ms": 450,
  "success": true,
  "error": null
}

日志会自动轮换（7天后删除）。

Docker部署

# Start MCP server
docker-compose up -d

# Check health
curl http://localhost:8080/health

# View logs
docker-compose logs -f mcp

# Stop server
docker-compose down

发展

# Install dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run with coverage
uv run pytest --cov

# Run linting
uv run pre-commit run --all-files

# Type checking
uv run mypy src/

当前测试覆盖率

211测试通过 （168台+43台集成）
53%以上的代码覆盖率 （仅限单元测试）
所有解析器和工具处理程序的单元测试
实际API调用的集成测试（BDNS、BOE、INE、datos.gob.es）

数据源

来源	API	说明
BDNS	昂首阔步	国家资助数据库
BOE	开放数据	官方公报和立法
的	API手册	国家统计研究所
数据.gob.es	API数据	国家开放数据目录

故障排除

Claude Desktop看不到MCP

检查配置文件路径是否正确
确保 uv 在你的路径中
验证 cwd 路径指向项目目录
完全重新启动克劳德桌面

API返回空结果

BOE/BORME不在周末或节假日发布
BDNS可能有速率限制
INE数据定期更新（每月、每季度）

工具调用错误

查看日志 logs/mcp_calls_YYYY-MM-DD.jsonl 获取详细的错误信息。

许可证

麻省理工学院