Spanish Public Info Radar MCP

🚀 西班牙公共数据MCP

西班牙公共数据MCP是一个用于查询西班牙政府开放数据API的MCP服务器，提供了对西班牙政府数据进行即时查询的LLM友好工具。

🚀 快速开始

安装

# 克隆仓库
git clone https://github.com/mjgmario/spanish-public-info-radar-mcp.git
cd spanish-public-data-mcp

# 使用uv安装（推荐）
uv sync

# 开发环境安装
uv sync --extra dev

启动方式

方式一：直接运行（开发/测试）

# 安装依赖
uv sync

# 运行MCP服务器（HTTP/SSE模式）
uv run python -m public_radar

# 或者指定端口运行
uv run python -m public_radar --port 9000

# 或者以标准输入输出模式运行（适用于Claude Desktop）
uv run python -m public_radar --stdio

方式二：使用Docker

# 构建并运行
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止运行
docker-compose down

验证运行情况

# 健康检查（HTTP模式）
curl http://localhost:8080/health

# 应返回: {"status":"healthy","service":"spanish-public-data-mcp"}

与Claude Desktop集成

步骤1：定位配置文件

Claude Desktop配置文件位置如下：

• Windows：%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

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

步骤4：验证连接

向Claude询问：“你有哪些西班牙公共数据工具可用？” Claude应返回26个可用工具的相关信息。

✨ 主要特性

• 多数据源支持：支持查询多个西班牙政府数据源，包括国家资助数据库（BDNS）、官方公报（BOE）、公司注册公报（BORME）、国家统计局（INE）和国家开放数据目录（datos.gob.es）。
• 即时查询：通过即时查询官方API获取数据，无需数据库。
• 丰富工具集：提供26个MCP工具，涵盖资助、立法、公司注册、统计和开放数据等多个领域。

📦 安装指南

# 克隆仓库
git clone https://github.com/mjgmario/spanish-public-info-radar-mcp.git
cd spanish-public-data-mcp

# 使用uv安装（推荐）
uv sync

# 开发环境安装
uv sync --extra dev

💻 使用示例

示例查询Claude

资助与补贴（BDNS）

"查找上个月发布的资助项目"

"搜索与创新或研发相关的资助项目"

"公司NIF为B12345678的获得了哪些资助？"

"显示资助项目BDNS 123456的详细信息"

立法（BOE）

"搜索有关可再生能源的法律"

"今天官方公报发布了什么内容？"

"查找2023年有关公共补贴的立法"

"显示数据保护法的全文"

公司注册（BORME）

"今天马德里注册了哪些公司？"

"显示2024年1月15日的公司注册公报摘要"

"查找近期公司解散情况"

统计（INE）

"国家统计局有哪些统计操作可用？"

"显示最新的消费者物价指数（IPC）数据"

"获取劳动力调查（EPA）的失业统计数据"

"西班牙当前的通货膨胀率是多少？"

"显示过去12个季度的国内生产总值（GDP）增长数据"

"在人口普查操作中查找有关人口的表格"

综合研究

"我想调查XYZ公司。检查：
1. 他们获得了哪些资助？
2. 有关他们的最新公司注册公报条目？"

"查找可再生能源项目的所有资金机会：
1. 当前开放的资助项目
2. 相关立法"

"给我一份西班牙的经济概况：
1. 最新的失业率（EPA）
2. 当前的通货膨胀率（IPC）
3. 近期的GDP增长情况"

开放数据（datos.gob.es）

"搜索有关空气质量的数据集"

"查找马德里市议会的开放数据"

"datos.gob.es上有哪些数据类别？"

"显示数据集e05068001-mapas-estrategicos-de-ruido的详细信息"

📚 详细文档

可用的MCP工具

BDNS（资助） - 3个工具

BOE（立法） - 11个工具

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

INE（统计） - 6个工具

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

通用 - 1个工具

工具参数参考

search_grants

{
  "date_from": "2024-01-01",    // 可选：开始日期 (YYYY-MM-DD)
  "date_to": "2024-12-31",      // 可选：结束日期 (YYYY-MM-DD)
  "granting_body": "E00003901", // 可选：资助机构代码
  "limit": 20                   // 可选：最大结果数 (1-100, 默认20)
}

search_grant_awards

{
  "date_from": "2024-01-01",      // 可选：开始日期
  "date_to": "2024-12-31",        // 可选：结束日期
  "beneficiary_nif": "B12345678", // 可选：受益方NIF/CIF
  "limit": 20                     // 可选：最大结果数
}

get_grant_details

{
  "grant_id": "123456"  // 必需：BDNS资助项目ID
}

search_legislation

{
  "query": "energias renovables",  // 必需：搜索文本
  "date_from": "2020-01-01",       // 可选：开始日期
  "date_to": "2024-12-31",         // 可选：结束日期
  "title": "ley energia",          // 可选：按标题过滤
  "department_code": "4225",       // 可选：部门代码（使用get_departments_table）
  "legal_range_code": "ley",       // 可选：法律范围（使用get_legal_ranges_table）
  "matter_code": "170",            // 可选：主题代码（使用get_matters_table）
  "include_derogated": false,      // 可选：包括已废除的法律（默认false）
  "offset": 0,                     // 可选：跳过结果（分页）
  "limit": 20                      // 可选：最大结果数 (1-100)
}

get_legislation_details

{
  "legislation_id": "BOE-A-2015-10566"  // 必需：BOE立法ID
}

get_legislation_text

{
  "legislation_id": "BOE-A-2015-10566"  // 必需：BOE立法ID
}

get_legislation_structure

{
  "legislation_id": "BOE-A-2015-10566"  // 必需：BOE立法ID
}

get_legislation_block

{
  "legislation_id": "BOE-A-2015-10566", // 必需：BOE立法ID
  "block_id": "a1"                       // 必需：块ID（例如，"a1" 表示第1条）
}

get_departments_table

{}  // 无需参数

get_legal_ranges_table

{}  // 无需参数

get_matters_table

{}  // 无需参数

get_boe_summary

{
  "date": "2024-01-15"  // 可选：日期 (YYYY-MM-DD)，默认为今天
}

get_borme_summary

{
  "date": "2024-01-15"  // 可选：日期 (YYYY-MM-DD)，默认为今天
}

get_ine_operations

{}  // 无需参数

get_ine_operation

{
  "operation_id": "IPC"  // 必需：操作ID或代码（例如，'IPC', 'EPA', '25'）
}

get_ine_table_data

{
  "table_id": "50902",  // 必需：国家统计局的表格ID
  "nult": 12            // 可选：最后周期数 (1-100, 默认12)
}

get_ine_series_data

{
  "series_code": "IPC251856", // 必需：国家统计局的系列代码
  "nult": 12                   // 可选：最后周期数 (1-100, 默认12)
}

search_ine_tables

{
  "operation_id": "IPC"  // 必需：搜索表格的操作ID
}

get_ine_variables

{
  "operation_id": "IPC"  // 可选：按操作过滤变量
}

search_open_data

{
  "query": "air quality",           // 可选：搜索文本
  "theme": "medio-ambiente",        // 可选：主题代码
  "publisher": "L01280796",         // 可选：发布者ID
  "limit": 20                       // 可选：最大结果数 (1-100)
}

get_open_data_details

{
  "dataset_id": "e05068001-mapas-estrategicos-de-ruido"  // 必需：数据集ID
}

list_open_data_themes

{}  // 无需参数

list_open_data_publishers

{
  "limit": 50  // 可选：最大结果数（默认50）
}

项目结构

src/public_radar/
├── common/          # HTTP客户端、日期处理、日志记录
├── sources/         # API客户端（BDNS、BOE、INE、datos.gob.es）
│   ├── bdns.py      # BDNS客户端（资助）
│   ├── boe.py       # BOE客户端（立法、BORME）
│   ├── ine.py       # INE客户端（统计）
│   └── datos_gob.py # datos.gob.es客户端（开放数据）
├── mcp/             # MCP服务器和工具
│   ├── server.py    # MCP服务器 + 26个工具处理程序
│   └── logging.py   # 工具调用日志记录（JSONL）
├── __init__.py
└── __main__.py      # CLI入口点

tests/
├── unit/            # 带模拟的单元测试（168个测试）
├── integration/     # 真实API测试（43个测试）
└── fixtures/        # 示例API响应

配置

环境变量

工具调用日志

所有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部署

# 启动MCP服务器
docker-compose up -d

# 检查健康状况
curl http://localhost:8080/health

# 查看日志
docker-compose logs -f mcp

# 停止服务器
docker-compose down

开发

# 安装开发依赖
uv sync --extra dev

# 运行测试
uv run pytest

# 运行测试并统计覆盖率
uv run pytest --cov

# 运行代码检查
uv run pre-commit run --all-files

# 类型检查
uv run mypy src/

当前测试覆盖率

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

数据源

🔧 技术细节

• 架构：即时查询官方API，无需数据库。
• 测试：包含211个测试（168个单元测试 + 43个集成测试），单元测试覆盖率达53%以上。
• 日志：所有MCP工具调用记录到logs/mcp_calls_YYYY-MM-DD.jsonl，日志自动轮转（7天后删除）。

📄 许可证

本项目采用MIT许可证。

🔍 故障排除

Claude Desktop无法识别MCP

1. 检查配置文件路径是否正确。
2. 确保uv在你的PATH环境变量中。
3. 验证cwd路径指向项目目录。
4. 完全重启Claude Desktop。

API返回空结果

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

工具调用错误

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