getyourguide-mcp

getyourguide-mcp

GetYourGuide 向けの MCP サーバーです。GetYourGuide Partner API を通じて、ツアーやアクティビティの検索、ツアー詳細、予約可能なオプション、レビューの取得を行えます。

🤖 このプロジェクトは AI（Claude Code）によって開発・保守されています。 ご自身の判断でご利用ください。

• npm： npmjs.com/package/getyourguide-mcp
• ソース： github.com/chrischall/getyourguide-mcp

ツール

すべてのツールは読み取り専用です。このサーバーは書き込みツールを登録しません。

ツール	機能
gyg_search_tours	フリーテキスト、場所、カテゴリー、日付範囲でツアー／アクティビティを検索します。並べ替え可能です。view
gyg_get_tour	数値 ID で指定したツアー 1 件の全記録。view
gyg_get_tour_options	ツアーの予約可能なオプション（チケット種別、時間帯）。必要に応じて日付範囲を指定できます。view
gyg_get_tour_availability	ツアーの予約状況：参加者カテゴリー、追加オプション、予約可能な日付。view
gyg_get_tour_reviews	ツアーのカスタマーレビュー。view
gyg_list_categories	アクティビティのカテゴリー（ID は gyg_search_tours ／ gyg_list_category_tours に渡します）。view
gyg_list_category_tours	1 つのカテゴリーに属するツアー。view
gyg_get_location	ID で指定した場所（都市、POI、地域）の詳細。view
gyg_list_location_tours	1 つの場所で利用できるツアー。view
gyg_healthcheck	認証情報と上流への接続を確認します。失敗は例外ではなくデータとして報告します

view — レスポンス形式

すべてのデータツールは view: "compact" | "full" を受け取り、デフォルトは compact です。求めないと効率化されないのであれば、通常それは効率化とは言えません。そのためオプトイン方式ではありません。gyg_search_tours の従来の compact: true フラグは廃止されました。

• compact — 3 つのツアー一覧ツールでは、ドキュメントに記載された簡潔な射影（tour_id、title、abstract、url、price、overall_rating、number_of_ratings、durations、categories、locations）を返し、{ _metadata, tours } にフラット化します。gyg_get_tour では 1 件の記録を返し、一覧形式のエンベロープを射影する必要がないため、また他のすべてのツール（オプション、予約状況、レビュー、カテゴリー、場所）では、画像 URL を除き、それ以外はすべて保持します。
• full — GetYourGuide の検証済みレコード全体を変更せずに返します。

射影に含まれないフィールド（画像のバリエーション、座標、マーケティング用の文章）が必要な場合は、full を使用してください。どちらの形式でも、すべてのレスポンスは空白を削除した JSON です。値の内部にある空白は削除されません。

セットアップ

GetYourGuide Partner API キーが必要です。partner.getyourguide.com で無料のパートナープログラムに登録し、ダッシュボードから API キーをコピーしてください。各リクエストでは、このキーが X-ACCESS-TOKEN ヘッダーとして送信されます。

Claude Code ／あらゆる MCP ホスト

{
  "mcpServers": {
    "getyourguide": {
      "command": "npx",
      "args": ["-y", "getyourguide-mcp"],
      "env": {
        "GYG_API_KEY": "your-partner-api-key"
      }
    }
  }
}

キーを設定しなくてもサーバーは起動します（そのため、ホストはインストール時に tools/list を確認できます）。最初のツール呼び出し時に、設定すべき環境変数を示す実行可能なエラーメッセージが返されます。

環境変数

変数	必須	意味
GYG_API_KEY	はい（ツール呼び出し時）	X-ACCESS-TOKEN として送信される Partner API キー
GYG_CURRENCY	いいえ	価格のデフォルト通貨（ISO 4217。未設定の場合は USD。API で必須です）。呼び出しごとの currency 引数で上書きできます
GYG_LANGUAGE	いいえ	コンテンツのデフォルト言語（未設定の場合は en。API で必須です）。呼び出しごとの language 引数で上書きできます
GYG_BASE_URL	いいえ	API のベース URL（デフォルトは https://api.getyourguide.com/1）
GYG_REQUEST_TIMEOUT_MS	いいえ	リクエストごとのタイムアウト（デフォルトは 30000）

ローカルで開発する場合は、これらをサーバーと同じディレクトリにある .env に記述してください（Git の追跡対象外です。.env.example を参照）。

動作に関する注意事項

• レート制限： 429／503 の場合、Retry-After に従って自動で1回再試行します（上限は10秒です）。それでも失敗した場合は、リクエストを控えるよう案内するエラーが表示されます。
• タイムアウトとネットワーク障害： リクエストが GYG_REQUEST_TIMEOUT_MS を超えた場合、または API に到達しなかった場合（DNS、接続拒否、リセット）は、リクエストパスを示すツールエラーが返され、タイムアウトを延長するか GYG_BASE_URL とネットワークを確認するよう案内されます。呼び出しのキャンセルはラップされず、キャンセルとして扱われます。
• 空の引数： 空文字列のクエリパラメーター（例：currency: "" や language: ""）は送信せずに削除されるため、API が空の値を拒否する代わりに、環境変数のデフォルト値／USD／en のフォールバックが適用されます。
• 認証エラー： 401／403 の場合、考えられる原因として、キーが間違っているか、そのキーのパートナーティアがエンドポイントに対応していないことの両方が示されます。
• API の変更： レスポンスは寛容に検証されます。想定外の形式の場合、サーバーは標準エラー出力に詳細な警告を記録し、処理を中断せずに未加工のレスポンスを返します。docs/GETYOURGUIDE-API.md を参照してください。ルートとリクエスト形式は API および公式 OpenAPI 仕様に照らして実環境で検証済みです。実際の 200 レスポンス本文は、キーを使った取得データから確定する必要があります。
• extraParams： gyg_search_tours と gyg_get_tour_options は、スキーマで定義されていない生のクエリパラメーターを渡すための extraParams を受け付けます。ツール独自の引数（limit、offset、currency、cnt_language、q など）とキーが競合する場合は、無視されます。常に型付き引数、またはそのデフォルト値が優先されます。（2.1.6 より前は、extraParams がこれらの値を上書きしていました。）
• シークレット： 上流から返されたエラー本文は、ツールの結果に含める前に機密情報を伏せてから切り詰められます。API キーが出力されることはありません。

開発

npm install
npm run build          # tsc + esbuild bundle → dist/
npm test               # tsc typecheck + vitest (no network — everything mocked)
npm run test:coverage  # tsc typecheck + the CI gate: 100% lines/branches/functions/statements

リリースは release-please で自動化されています。バージョンを手動で更新しないでください。リポジトリではスカッシュマージを行うため、PR タイトルには Conventional Commits（feat:、fix: など）を使用してください。

ライセンス

MIT