ayudas-es

ayudas-es-mcp

スペインの助成金・補助金 MCP サーバーの使用ガイドです。

キーやスクレイピングなしで、AI が2つの公式情報源を参照できます。

• BDNS (infosubvenciones.es)： 国、自治州、県、自治体など、すべての行政機関の助成金・補助金の公募情報。
• BOE (オープンデータ)： 法令、採用試験、入札情報。

検索はリアルタイムで行われます。データベースのダウンロードや同期は不要です。 インストールすれば、そのまま動作します。

提供する機能

BDNS の API に加えて、サーバーは次の機能を提供します。

• 推定値ではなく、正確な件数を表示します。
• 各公募の本文から申請期限を算出します。
• 実際に申請できる助成金を分けて表示します。
• PDF の公募要項を読み取り、引用ごとにページ番号を示します。
• 毎年繰り返される公募の予定カレンダーを表示します。
• わからないことは黙って済ませず、明示的に知らせます。

1. 要件

• Node.js 22.13 以降。
• MCP 対応クライアント（Claude Code、Claude Desktop、Cursor など）。

ほかにインストールするものや、設定するキーはありません。

2. インストール

Claude Code

claude mcp add ayudas -- npx -y ayudas-es-mcp

Claude Desktop、Cursor、その他のクライアント

このブロックをクライアントの MCP 設定に追加し、再起動してください。

{
  "mcpServers": {
    "ayudas": {
      "command": "npx",
      "args": ["-y", "ayudas-es-mcp"]
    }
  }
}

3. 動作確認

ターミナルで次を実行します。

npx ayudas-es-mcp --version

クライアントで、たとえば「ガリシア州でデジタル化に取り組む自営業者向けに、現在申請できる助成金はありますか？」と質問してください。サーバーが稼働していれば、AI は ayudas_* ツールを使用します。

4. 質問できること

• 「バスク地方の中小企業向けに、今後2か月で公募されそうな助成金はありますか？」
• 「毎年この時期に公募される助成金で、今年はまだ公募されていないものはありますか？」
• 「今年、住宅助成金を最も多く公募した自治州はどこですか？」
• 「5月以降、中小企業向けの助成金は毎月いくつ公募されましたか？」
• 「アンダルシア州の宿泊・飲食業の中小企業向けに、今週のまとめを作成してください。」
• 「今月、BOE で看護師の採用試験が公示されましたか？」

クライアントでコマンド（/）として表示されるプロンプトが2つあります。

プロンプト	用途
ayudas_para_mi	プロフィール（「自営業、ビルバオの美容院」など）をもとに、申請受付中の助成金、まもなく公募される傾向にある助成金、最有力の助成金の要件を表で返します。
analizar_convocatoria	公募コードをもとに、公募の詳細（申請期限、金額、要件、必要書類）をページ番号付きで引用して作成します。

5. ツール

すべて読み取り専用（MCP のアノテーション）なので、対応するクライアントでは呼び出しごとに確認を求められません。定義済みの値（自治州、受益者、目的など）は、大文字・アクセント記号・一般的な名称に対応しています。「País Vasco」「Euskadi」「pymes」は、pais-vasco や autonomo-o-pyme と同じ値として扱われます。

ツール	機能
ayudas_buscar	テキスト、自治州、受益者、目的、支援手段、行政機関で検索します。正確な合計件数と、ステータス、期限、予算を含むサンプルを返します。
ayudas_recuento	自治州、目的、受益者、支援手段、行政機関、機関、月、年ごとの正確な件数とランキングを返します。
ayudas_previstas	予定カレンダー：毎年公募される支援のうち、2021年以降の過去の実績から、まもなく公募されるもの、または遅れているものを表示します。
ayuda_detalle	完全な詳細情報：解釈済みの期限、公式要約、要項、文書、履歴を表示します。
ayuda_texto	要項の PDF を読み取り、各項目の原文をページ番号とともに返します。
novedades_perfil	プロフィール別のニュースレター：終了していない新しい支援と、関連テーマに関する BOE の情報を掲載します。協定や学習計画は含みません。あるテーマで結果が見つからない場合は、接頭辞を使って再検索し、その旨を示します。
estado_datos	データの出典、キャッシュの状態、カレンダーの状態を表示します。
boe_sumario_dia	ある日の BOE 掲載情報を表示します。キーワードとセクションで絞り込めます。
boe_buscar	日付範囲、キーワード、セクション（公務員採用試験は 2B、入札は 5A）で BOE を検索します。
boe_documento	BOE の法令文書のテキストを表示します。

また、サーバーはモデルに指示を送ります。件数の集計や要件の確認に使うツールを指定し、架空の情報で補わずにコードや注意事項を引用するよう促します。

6. 設定

npx ayudas-es-mcp --help
npx ayudas-es-mcp --version
npx ayudas-es-mcp --vaciar-cache

任意の環境変数：

変数	制御する内容	デフォルト
AYUDAS_CACHE	キャッシュファイルのパス	~/.cache/ayudas-es-mcp/cache.sqlite
BDNS_INTERVALO_MS	BDNS へのリクエスト間の待機時間	1000
AYUDAS_TIMEOUT_MS	リクエストごとのタイムアウト	30000

キャッシュ

リクエストの重複を避けるため、応答はディスクに保存されます（書き込みできない場合はメモリにのみ保存されます）。BDNS の複製ではなく、すでに照会した内容だけを保存します。データの変更頻度に応じて、有効期間が異なります。

データ	保存期間
7 日以上前に終了した期間の合計件数と一覧	1 週間
直近の日付を含む合計件数と一覧	1 時間
期限が暫定の詳細情報（要約が未公開）	1 日
公募が終了した、または申請を受け付けていない場合の詳細情報	1 か月
その他の詳細情報	1 週間
PDF から抽出したテキスト	1 か月
予定カレンダー	1 週間
1 か月以上前に終了した年の履歴（カレンダー用、圧縮形式）	6 か月
当年の履歴（カレンダー用、圧縮形式）	1 日

カレンダーの履歴は、ディスク上で約 25 MB（1 年あたり約 4 MB）を使用します。

7. 仕組み

各質問は、BDNS の公式 APIへのクエリに変換されます。

• 1 回のリクエストで正確な合計件数を取得。 API は、検索結果をダウンロードせずに一致件数を返します。単純な件数集計は 1 回のリクエストで済み、ランキングの場合はグループごとに 1 回リクエストします。
• 2 段階のキーワード検索。 API は部分文字列で検索します（「tala」で検索すると「instalación」も見つかります）。各単語の語幹を送信し、返された結果に対して、後述する単語のルールを適用します。
• 表示する項目のみ詳細を取得。 期限、予算、種類は各公募の詳細情報に含まれており、表示するときにのみ取得します。
• 慎重なリクエスト頻度。 BDNS へのリクエストは最大で 1 秒に 1 回とし、連続したリクエストによる負荷を避けます。

単語検索

タイトル（およびバスク語、カタルーニャ語、ガリシア語の共同公式タイトル）を、アクセント記号を無視し、単語境界を考慮して検索します。単数形と複数形は同等に扱われ、「pyme」と「pymes」は同じ検索結果になります。また、*を付けると前方一致で検索されます（「digital*」は「digitalización」と「digitales」に一致します）。幅広いテーマを検索する場合は、finalidadを使うのがおすすめです。

一般的な用語は同義語も含めて検索されます。「autónomos」は「por cuenta propia」と「autoempleo」にも一致し、「pymes」は「pequeñas y medianas empresas」と「microempresa」にも、「vehículo eléctrico」は「movilidad eléctrica」と「MOVES」にも一致します。同義語の一覧はsrc/texto.tsにあり、実際のタイトルを確認したうえで、限定的な同義語のみを収録しています。「Consejería de Empleo」の「empleo」のように、機関名の一部になっていることが多い語は、主にノイズを増やすため除外しています。同義語を構成する単語は、順序どおりに連続している必要がありますが、間に最大2語まで挟むことができます。追加された検索語は応答に示され、sinonimos: falseを指定すると、入力した語だけで検索します。*を付けた単語は同義語に展開されません。一覧にない語については意味検索を行わないため、「digitalización」で「transformación tecnológica」は見つかりません。

同義語によって追加のリクエストが発生することはありません。APIが「次の単語のいずれか」による検索に対応しており、その後に完全一致フィルターを適用するためです。

各公募の申請期間

BDNSには、一部の公募についてしか申請期間の日付が掲載されていません。それ以外は申請期間がテキストで記載されており、AIを使わず、ルールに基づいて解釈します。

テキストの記載	結果
種別が「Concesión directa - instrumental」	申請できません。特定の受給者にすでに交付された助成金の記録です。
「Hasta el 30 de noviembre de 2026」、「31 de decembro」、「1/3/27」	日付に応じて、受付中または受付終了です（スペイン語、ガリシア語、カタルーニャ語）。
要約がすでに公開されており、「掲載日の翌日から10営業日」のように記載	カレンダーに基づいて終了日を計算します。
同じ記載で、要約が未公開	公開待ちです。
「Sin plazo de solicitud」、「no procede」、「nominativa」	申請できません。
申請期間が複数ある場合、または標準的でない開始日の場合	日付を推測せず、確認を促します。

計算は法律39/2015第30条に従います。営業日には土曜日、日曜日、祝日を含めません。月の期限は満了月の同じ日とし、最終日が非営業日の場合は次の営業日に繰り越します。国および自治州の祝日はNager.Dateから取得します。地方の祝日は含まれないため、応答では必ず計算結果であることと計算方法を示します。手作業で確認済みのケースはsrc/plazos.test.tsにあります。

公募要項の閲覧（PDF）

ayuda_textoは公募のPDFをダウンロードし、要約やAIによる処理をせず、ページ番号付きの原文テキストを返します。これは要求された場合にのみ実行され、各文書は一度だけ処理されます。

• 文書名に基づいて文書を選びます。「texto íntegro」または「bases」を、付属資料、申請書、承認決定より優先します。選択した文書を読み取れない場合は次の文書に進み、そのことを伝えます。応答には、documentoで指定して取得できるその他の文書も一覧表示します。
• 見出し（Artículo、Base、「Primero.-」、「6. Plazo…」、大文字表記など）から項目を特定します。対応する見出しがある場合は「項目」、テーマに言及しているだけの場合は「言及」として区別します。
• 項目を認識できない場合は、buscarとpaginasを使って、特定の語句やページを直接検索できます。
• 金額（ユーロ）を、各金額が記載されている文とあわせて抽出します。
• PDFの内容は外部文書からの原文テキストとして示され、指示として扱われません。

制限事項：OCRには対応していないため、テキストレイヤーのないスキャンPDFは読み取れません。Word文書やその他の形式も読み取れません。また、25 MBまたは200ページを超えるファイルは、最初の部分のみを読み取ります。項目の検出にはルールを使うため、引用されたページを確認することをおすすめします。

予定カレンダー

同じ機関が同じタイトルで実施する公募は、年、日付、回次を除いてまとめます （「XIV Premios X 2026」は「XV Premios X 2027」と同じものとして扱います）。3年以上にわたって公募されているものは、通常の登録日とその変動を示すシリーズとしてまとめます。申請できない記名式助成、直接助成、協定は除外します。

各シリーズには、公募された年数と日付の規則性に応じて、信頼度（高、中、低）が付きます。前年の登録日が通常の時期から大きく外れていた場合は、信頼度が1段階下がります。また、いずれかの年に公募されなかった場合、信頼度は「中」までです。「低」は既定では非表示です。シリーズによっては名称が変わったり、公募が終了したりするため、予定日は推定値です。ツールは各カレンダーで評価を計算して表示するため、AI はその信頼度を伝えることができます。

カレンダーには、2021年以降の履歴が必要です。助成金ツールが初めて使われたときにバックグラウンドで準備され、起動時には準備されません。その間、ayudas_previstas は「該当なし」と返すのではなく、準備中であることを知らせます。初回は約1分かかります。ダウンロードが完了するたびに各年のデータが保存されます。クライアントが途中で終了した場合、次回は未取得の年から再開します。毎週更新される際は、当年分だけを再ダウンロードするため、約20秒で完了します。

8. 誤った情報を提供しないための対策

リスク	対応
検索で見つからなかっただけなのに「助成金はありません」と伝える	空の検索結果には注意書きが付きます。検索はタイトルの語句で行われるため、助成金が存在しない証明にはなりません。
サンプルを全件として数える	ayudas_buscar は正確な総数を返し、一覧がサンプルであることを示します。件数の確認には ayudas_recuento を使います。
国の助成金と自治州の助成金を混同する	各情報には対象範囲が示されます。スペイン全土を対象とするものは、別の自治州の機関が公募していても「ESTATAL」と表示されます。
すでに申請できない助成金	終了済み、申請不要（直接助成）、受付中を区別し、制度上の助成も別に扱います。
一部の予算を合算する	BDNS では予算の総額が提供されないため、件数の集計では予算を合算しません。各公募の予算は個別の情報に記載されています。
直近90日分だけを確認していることを明示しない	その旨を示し、同じフィルターでそれ以前に登録された件数も数えます。
質問に対して何千行ものデータをダウンロードする	直接助成を除外するために30,000行を超えるデータのダウンロードが必要な場合は、条件を絞るよう求めます。
深夜に「今日」の日付が誤る	日付は UTC ではなく、スペイン本土時間で扱います。
情報源の応答が遅い、または停止している	各リクエストにはタイムアウトと再試行が設定されており、応答が途中で途切れた場合も同様です。一時的な障害で応答全体が失敗することはなく、不足している情報を知らせます。
同義語で検索範囲が広がりすぎる	追加した語句を応答で示します。sinonimos: false を指定すると、入力した語句だけで検索します。
カレンダーの準備がまだできていない	「継続的な助成金は0件」ではなく、準備中であることを伝えます。
年に複数の助成金があるシリーズをカレンダーに掲載する	同じタイトルで機関が複数の助成金を登録しているシリーズを示します。
PDF に存在しない内容を引用する	ページ番号付きで原文を返し、項目としての記載と単なる言及を区別します。該当するテーマが見つからない場合はその旨を知らせます。
指示が含まれる PDF の文章	外部文書の原文データとして明示して提供します。
存在しないコード	再試行せず、明確なエラーをすぐに返します。

9. 既知の制限事項

• 助成金の状態。 BDNS には公募が受付中かどうかが示されていません（abierto フィールドは常に false で、受付中および種類のフィルターは黙って無視されます）。そのため、解釈した申請期間から推定します。計算された申請期間には、地域の祝日は含まれません。
• 直接交付。 どの公募が直接交付なのかを確実に判断できるのは、各公募の詳細を確認した場合のみです。検索と件数集計では、excluir_directas フィルターはタイトルから推定するため、すべてを検出できるわけではありません。このフィルターを使わない件数集計には直接交付も含まれ、その旨が通知されます。
• 予算と古い助成金。 予算と申請期間は各公募の詳細ページにのみ記載されているため、件数集計では予算を合算せず、検索では数か月前に登録され、現在も受付中の助成金を見つけられません（期間開始前に該当するものがいくつあるかを通知します）。
• 初回のランキング。 自治州または目的別のグループ化にはグループごとにリクエストが必要で、時間がかかる場合があります。2 回目以降はキャッシュから取得されます。
• カレンダー。 BDNS への登録時期を予測するものであり、申請期間は予測しません。また、名称が変更された助成金は検出できません。
• 自治州。 BDNS では、一部の公募に自治州が割り当てられていません。
• 同じタイトル、異なる助成金。 同じタイトルで個別の助成金を何十件も登録する機関があります。これらは重複ではないため、削除されません。
• PDF の読み取り。 OCR は使用せず、AI ではなくルールに基づいて読み取ります。
• 複数のインスタンス。 1 秒あたり 1 リクエストの制限はプロセス単位です。複数のクライアントを同時に開くと、それぞれのリクエスト頻度が合算されます。ただし、ディスク上のキャッシュは共有されます。

10. 開発

git clone … && cd ayudas-es-mcp
npm install
npm run build
npm test            # pruebas sin red: plazos, lectura de documentos, fechas, caché
npm run test:live   # búsqueda en directo frente a la referencia + prueba de extremo a extremo

データとライセンス

コードは MIT ライセンスで配布されています（LICENSE を参照）。

• BDNS。 データの提供元：スペイン国家行政総監局。データは、商用・非商用を問わず出典を明記し、情報の本質を損なわないことを条件とする法的通知に基づいて再利用しています。このサーバーは公募のみを照会し、受給者の個人データは扱いません。
• BOE。 データの提供元：スペイン国家官報庁のオープンデータ API。データは、boe.es へのリンクを付け、支持を受けているかのような表現をせず、出典を明記することを条件に、商用・非商用を問わず再利用できる法的通知に基づいて再利用しています。
• 祝日。 Nager.Date、祝日の公開 API。

本プロジェクトは独立したものであり、IGAE、スペイン国家官報庁、またはその他の公的機関とは提携しておらず、これらの機関から支持を受けているものでもありません。情報は提供元で変更または修正される場合があります。申請を提出する前に、必ず公式ページで確認してください。