shield_lock
JinDaGe
← Back to MCP directory
publicPublicdnsLocal runtime

spanish-public-info-radar-mcp

西班牙公共数据MCP服务器，提供26个工具查询西班牙政府开放数据，包括补助金、法规、公司注册、统计数据和开放数据目录。

article

README

🚀 西班牙公共数据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个工具

| 工具 | 描述 | |------|-------------| | search_grants | 按日期范围和资助机构搜索资助项目 | | search_grant_awards | 按日期范围和受益方NIF搜索已授予的资助项目 | | get_grant_details | 获取特定资助项目的详细信息 |

BOE（立法） - 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 | 获取特定日期的官方公报每日摘要（带过滤器） |

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 | 获取可用数据源和工具的概述 |

工具参数参考

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_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部署

# 启动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 | 描述 | |--------|-----|-------------| | BDNS | Swagger | 国家资助数据库 | | BOE | 开放数据 | 官方公报与立法 | | INE | API手册 | 国家统计局 | | datos.gob.es | API数据 | 国家开放数据目录 |

🔧 技术细节

  • 架构：即时查询官方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中的日志以获取详细错误信息。

help

Runtime guide

cloud

Hosted runtime

Hosted servers run from a provider-managed environment. You usually connect the MCP client to the hosted endpoint or follow the provider's authorization flow, without keeping a local process alive

  1. Open provider connection page
  2. Authorize or copy endpoint
  3. Connect from your MCP client
terminal

Local runtime / other methods

Local servers run on your own machine or infrastructure. You normally copy the server_config into your MCP client, install the required package, and provide env variables from env_schema when needed

  1. Copy server_config
  2. Install required package
  3. Fill env variables and restart client