Spanish Public Info Radar MCP

🚀 スペイン公共データMCP

このプロジェクトは、スペイン政府のオープンデータAPIをクエリするためのMCPサーバーです。LLMに友好的なツールを提供し、様々なデータソースからリアルタイムにデータを取得できます。

🚀 クイックスタート

スペイン公共データMCPは、スペイン政府のデータをオンザフライでクエリするためのLLMに友好的なツールを提供します。以下の主要なデータソースをサポートしています。

• BDNS - 国家助成金データベース（助成金や補助金）
• BOE - 官報（統合された法律）
• BORME - 会社登記官報（会社の行為）
• INE - 国家統計研究所（公式統計）
• datos.gob.es - 国家オープンデータカタログ（40,000以上のデータセット）

アーキテクチャ：公式APIへのオンザフライクエリ。データベースは不要です。 合計：26のMCPツール | 211のテスト | 53%以上のカバレッジ

📦 インストール

# リポジトリをクローン
git clone https://github.com/mjgmario/spanish-public-info-radar-mcp.git
cd spanish-public-data-mcp

# uvを使用してインストール（推奨）
uv sync

# 開発用
uv sync --extra dev

💻 使用例

基本的な使用法

オプション1: 直接実行（開発/テスト用）

# 依存関係をインストール
uv sync

# MCPサーバーを実行（HTTP/SSEモード）
uv run python -m public_radar

# 特定のポートで実行
uv run python -m public_radar --port 9000

# stdioモードで実行（Claude Desktop用）
uv run python -m public_radar --stdio

オプション2: 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に「What Spanish public data tools do you have available?」と尋ねます。Claudeは26の利用可能なツールに関する情報を返すはずです。

✨ 主な機能

利用可能なMCPツール

BDNS（助成金） - 3つのツール

BOE（法律） - 11のツール

BORME（会社登記） - 1つのツール

INE（統計） - 6つのツール

datos.gob.es（オープンデータ） - 4つのツール

一般 - 1つのツール

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"

法律（BOE）

"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"

📚 詳細ドキュメント

ツールパラメーターリファレンス

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",  // 必須: INEのテーブルID
  "nult": 12            // オプション: 最後の期間の数 (1-100, デフォルト12)
}

get_ine_series_data

{
  "series_code": "IPC251856", // 必須: INEのシリーズコード
  "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）の統合テスト

データソース

トラブルシューティング

Claude DesktopがMCPを認識しない場合

1. 設定ファイルのパスが正しいことを確認してください。
2. uvがPATHに含まれていることを確認してください。
3. cwdパスがプロジェクトディレクトリを指していることを確認してください。
4. Claude Desktopを完全に再起動してください。

APIが空の結果を返す場合

• BOE/BORMEは週末または休日には公開されません。
• BDNSにはレート制限がある場合があります。
• INEのデータは定期的（月次、四半期ごと）に更新されます。

ツール呼び出しエラーの場合

logs/mcp_calls_YYYY-MM-DD.jsonlのログを確認して、詳細なエラー情報を取得してください。

📄 ライセンス

MIT