<SYSTEM>Developers: 開発者向け（MCP / REST API の仕様、利用条件、ツールの一覧）</SYSTEM>

# MCP / API の仕様

> Retro Game Gather の MCP サーバーと REST API の接続先・認証・権限・プラン・応答形式・更新と削除の契約

Retro Game Gather（RGG）は、日本で発売されたレトロゲームのデータベースと、利用者の記録（マイライブラリ・ウィッシュリスト・プレイ記録など）を、MCP と REST API で提供します。どちらもツールを呼び出す形で、ツールの名前・引数・結果は共通です。REST API は 66 のツールを提供し、MCP はそのうちファイル出力の 2 つを除く 64 のツールを提供します。 RGG が提供するのは、ゲームの検索・参照、記録の追加・更新・削除、確定的な集計、ファイル出力（REST API のみ）です。紹介文の作成やおすすめは、呼び出し側（AIツールやプログラム）の役割です。 ## 接続先 | 方式 | 接続先 | 認証 | | -------- | -------------------------------------- | ------------------- | | MCP | `https://game.retrogather.com/mcp` | OAuth 2.1、または APIキー | | REST API | `https://game.retrogather.com/rest/v1` | APIキー | MCP はステートレスな Streamable HTTP で、POST だけを受け付けます（GET / DELETE は 405）。受け付けるプロトコルの版は `2026-07-28`、`2025-11-25`、`2025-06-18`、`2025-03-26` です。 REST API の呼び出し方は[REST API](/developers/rest-api/)、各ツールの一覧は[ツールリファレンス](/developers/tools/)、引数と応答の詳細は[API リファレンス](/developers/api/)を参照してください。 このドキュメントは、AIツール（コーディング用の AI など）に読ませるためのテキストでも公開しています。開発者向けのページだけなら [developers.txt](/_llms-txt/developers.txt)、全ページなら [llms-full.txt](/llms-full.txt) を渡してください。一覧は [llms.txt](/llms.txt) にあります。 ## 認証 ### OAuth（MCP） MCP クライアントは、RGG の認可サーバーで OAuth 2.1（認可コード + PKCE）の認可を受けます。認可サーバーのメタデータは `/.well-known/oauth-authorization-server`、保護リソースのメタデータは `/.well-known/oauth-protected-resource` で公開しています。クライアント登録は Client ID Metadata Document と動的クライアント登録の両方に対応します。 利用者は RGG にログインし、許可画面で許可する権限を選びます。アクセストークンはリフレッシュトークンで更新できます。 ### APIキー APIキーは、利用者が[ユーザー設定の MCP / API](/features/mcp-api/#api%E3%82%AD%E3%83%BC)で発行します。`Authorization: Bearer <APIキー>` の形で送ります。REST API と MCP の両方で使えます。 * キーは `rgg_` で始まり、発行時に一度だけ表示されます * 有効期限はありません。利用者が削除すると、数分以内に使えなくなります * 権限は発行時に決まり、あとから変更できません。別の権限が必要なら発行し直します * 1 人が持てる有効なキーは 10 件までです ## 権限（スコープ） ゲーム情報・ライブラリ・プレイ記録の 3 つの区分に、閲覧（read）・編集（write）・削除（delete）があります。ゲームマスタの一括ダウンロードだけは `games:bulk` です。OAuth と APIキーで同じ権限の語彙を使います。 | スコープ | 対象 | | ---------------- | -------------------------------------------------- | | `games:read` | ゲームの検索・詳細、プラットフォーム・発売元・ジャンルの一覧、ニュース、利用者のカスタムデータの閲覧 | | `games:write` | 利用者のカスタムデータ（プラットフォーム・発売元・ゲーム）の追加・変更 | | `games:delete` | 利用者のカスタムデータの削除 | | `games:bulk` | ゲームマスタの一括ダウンロード（`exportMasterData`）。APIキーだけで使います | | `library:read` | マイライブラリ、所有ソフト、ウィッシュリスト、ゲームタグ、マイコレクションの閲覧 | | `library:write` | 上記の追加・変更 | | `library:delete` | 上記の削除 | | `play:read` | プレイ記録、プレイログ、ゲーム機、メンテナンス記録の閲覧 | | `play:write` | 上記の追加・変更 | | `play:delete` | 上記の削除 | * write・delete・bulk は、同じ区分の read を含みます。delete は write を含みません * カスタムデータの write / delete で、RGG の公式データは変更できません * OAuth で最初に要求される権限は `games:read library:read library:write play:read play:write` です * 許可画面では、削除の権限を既定でオフにして表示します。プレミアムプランの利用者には、`games:write` も表示します。クライアントが要求していない権限も、利用者が許可画面で選べます * 既存のトークンに権限が後から加わることはありません。利用者が連携し直して選んだときだけ加わります * OAuth では `games:bulk` を発行しません * APIキーは、ゲーム情報の閲覧があれば `games:bulk` を含みます。プランが対応しているかは実行時に判定します 権限が足りない呼び出しは 403 になります。エラーの `message` は、足りない権限、連携し直す手順、何も変更していないことを英文で伝えます。`data` には `reason` と `scopes`（足りない権限）が入ります。 ## プラン ツールごとに使えるプラン（FREE / LIGHT / PREMIUM）が決まっています。プランで使えないツールは、そのプランのツール一覧に出ません。プランは実行時に判定し、プランの変更は最大 5 分で反映されます。 プランごとの違いは[MCP / API](/features/mcp-api/#%E3%83%97%E3%83%A9%E3%83%B3%E3%81%AB%E3%82%88%E3%82%8B%E9%81%95%E3%81%84)と[ツールリファレンス](/developers/tools/)を参照してください。登録件数の上限はアプリと共通で、`getAccount` で現在の件数と上限を取得できます。 ## 利用上限 利用者ごとに、MCP と REST API を合わせた 1 日の利用上限があります。上限はプランによって異なり、日本時間の 0 時にリセットされます。呼び出しの種類によって消費する量が異なり、一覧・検索・分析・ダウンロードは単件の参照より多く消費します。 * 上限に達すると 429 と `Retry-After` を返します。日次の上限では、再開時刻（`resetAt`）も返します * 短時間に集中した呼び出しも、一時的に 429 になります * 応答ヘッダーの `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset` で残量を確認できます * 利用者は、設定画面と `getAccount` の `usage` で今日の使用率（%）を確認できます * 本文を返せなかったダウンロードは、消費した分を戻します * 削除の確認（1 回目の呼び出し）は日次の上限を消費しません ## 応答 ### MCP の結果 すべてのツールが `inputSchema` と `outputSchema` を公開しています。結果の本体は `structuredContent` です。`content` は、短い要約と、`structuredContent` と同じ内容の JSON 文字列の 2 つのテキストで構成します。次の操作の案内は `structuredContent` の `hint` に入ります。 ### REST の結果 REST API は、`structuredContent` と同じ内容を JSON の本文として返します。 ### 値の表し方 * MCP は、値が無い項目を省略します（`null` を返しません） * REST は、ゲームの情報（検索・詳細と、一覧に含まれるゲーム）の値が無い項目を `null` で返します。[ファイル出力](/developers/rest-api/#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%87%BA%E5%8A%9B)の値が無い列も `null` です。REST を使う場合は、項目が無いことと `null` を、どちらも値が無いものとして扱ってください * 要求した配列グループが空の場合は、MCP・REST とも `[]` を返します * 日付は `YYYY-MM-DD`、日時は日本時間のオフセット付き（`+09:00`）です * `revision` は照合用の値です。解釈せず、そのまま送り返してください * 一覧の配列は `items` に入ります * ゲームの外部リンク（`externalLinks`）は、MCP では完成した URL、REST とファイル出力では外部サービスの ID で返します。REST の IGDB の ID は[IGDB の識別子](/developers/rest-api/#igdb-%E3%81%AE%E8%AD%98%E5%88%A5%E5%AD%90)を参照してください ### ページング 一覧は `page` と `limit` で取得します。続きがある場合は `hasMore` が `true` になります。条件・並び順・`fields`・`limit` を変えずに `page` を進めてください。取得中に更新されたデータの、時点を固定した取得は保証しません。 `fields` を指定すると、返すグループを選べます。省略するとツールごとの既定、`[]` は最小限の項目だけを返します。`fields` の内容によって 1 ページの上限件数が下がることがあり、その場合は `effectiveLimit`・`limitReduced`・`limitReason` で分かります。 ## 更新と競合 * 更新では、省略した項目はそのまま残ります。`null` を送ると値を解除し、配列に `[]` を送ると全件を解除します * ゲームタグやマイコレクションのゲームの集合を置き換える操作、所有ソフトの操作では、読み取り時の `revision` が必要です。書き込みが成功したときに返る新しい `revision` は、次の書き込みに使えます * `revision` が合わない場合は競合として拒否します。最新の状態を取得し直し、更新内容を組み直してから送ってください ## 削除の確認 削除は 2 回の呼び出しで実行します。 1. 1 回目は何も変更せず、削除する対象・一緒に消えるもの・`confirmToken` を返します 2. 同じ引数に `confirmToken` を加えて呼び出すと、削除を実行します `confirmToken` の有効期限は 10 分です。確認の間に対象が変わった場合は、実行せずに再確認を求めます。 **1 回目の結果を利用者に示し、同意を得てから 2 回目を呼び出すのは、呼び出し側の責務です。** RGG は、利用者が確認したかどうかを検証しません。 削除すると一緒に消えるデータがあります。たとえば `removeFromLibrary` は、そのゲームのプレイ記録・プレイログ・所有ソフトも削除します。 ## エラーの後の確認 * `saved: true` を含むエラーは、保存は完了しています。返された ID や結果を使い、同じ追加を送り直さないでください * 応答が失われた場合も、未保存とは限りません。各ツールの説明にある読み取り先で状態を確かめてから、再送するかを決めてください * 追加の直後に一覧に現れないことだけを理由に、再送しないでください。一覧への反映は遅れることがあります * プレミアムプランの再プレイ（`addPlayRecord` の `replay: true`）は、送るたびに新しい記録を作ります。結果が不明な場合は `getGamePlayHistory` で確かめてください * 一時的な失敗は `retryable: true` と `Retry-After` を返します。この場合は同じ呼び出しを再試行できます ## 提供範囲 ゲームデータベースの対象は、日本で発売されたレトロゲームです。現行の家庭用ゲーム機は対象外です。公式データは日次で更新されるため、訂正の反映に最大 1 日かかります。 次の操作は提供していません。 * 画像の登録・取得 * MCP でのファイル出力（REST API の `exportMyData`・`exportMasterData` を使います） * 属性の定義の編集、公式タグの編集・コピー * マイライブラリ以外の一括登録（マイライブラリは `addToLibraryBatch` で 1 回 100 件まで） * ニュースの設定・ブックマーク、ユーザー設定の変更 ## 利用条件 MCP・REST API で取得したゲームデータと、ダウンロードしたファイル（REST API のファイル出力、アプリのゲーム一覧のエクスポート）は、会員本人が次の範囲で利用できます。 * 個人での利用（自分の表計算での管理、AIツールでの分析など） * 会員が作るアプリ・ツール・サイトへの組み込み。この場合は、データの出典が Retro Game Gather であることを明示してください ダウンロードしたファイルそのもの、またはそれと実質的に同じ一覧を第三者に配布・公開することは、出典を明記した場合も含めて禁止しています（リポジトリやデータセットとしての公開を含みます）。アプリ・ツールに内包して画面に表示するのは、組み込みの範囲に含みます。 これらの条件の対象は、Retro Game Gather が提供するゲームデータ（ゲーム・プラットフォーム・発売元・ジャンル）です。自分で登録した記録や、プレミアムプランで追加したカスタムデータは自分のデータなので、`exportMyData` などで取得した場合も対象になりません。 * 外部サービスの ID・リンク先（IGDB、メディア芸術データベースなど）の利用は、各提供者の規約に従います 詳しくは[利用規約](https://retrogather.com/terms/)を参照してください。

# REST API

> APIキーで Retro Game Gather の REST API を呼び出す方法、MCP との違い、エラーとファイル出力の扱い

REST API は、MCP と同じツールを APIキーで呼び出す JSON API です。自作のスクリプトや集計ツールから、マイライブラリやプレイ記録を読み書きできます。ファイル出力（`exportMyData`・`exportMasterData`）は REST API だけで使えます。 権限・プラン・応答の共通の決まりは[MCP / API の仕様](/developers/overview/)を参照してください。 ## 準備 1. Retro Game Gather の[ユーザー設定の MCP / API](/features/mcp-api/#api%E3%82%AD%E3%83%BC)で APIキーを発行します 2. 用途に合った権限を選びます（読み取りだけなら「閲覧のみ」） 3. 表示されたキーを安全な場所に保管します APIキーは `Authorization` ヘッダーで送ります。 
```http
Authorization: Bearer <APIキー>
```
 キーが使えるかは、`getAccount` で確かめられます。プラン、登録件数と上限、今日の使用率が返れば、キーは有効です。 
```bash
curl -H "Authorization: Bearer <APIキー>" \
  https://game.retrogather.com/rest/v1/getAccount
```
 ## ツールの一覧と引数 各ツールの引数（名前・必須・型・許容値・件数の制約）と応答の形は、[API リファレンス](/developers/api/)で確認できます。このリファレンスは、次の公開カタログから生成しています。 | エンドポイント | 内容 | | --------------------------- | --------------------------- | | `GET /rest/v1/tools` | ツールのカタログ（JSON） | | `GET /rest/v1/openapi.json` | 同じカタログを OpenAPI 3.1 に変換したもの | * どちらも認証は不要で、利用上限も消費しません。APIキーを付けても付けなくても、同じ内容を返します * 定義は最上位のプラン（プレミアム）を基準にしています。自分のプランで使える範囲は、`getAccount` のプランと、各ツールの `plans`・`planDifferences` で判断します * 内容が変わると `revision`（OpenAPI では `x-rgg-revision`）が変わります。`ETag` も同じ値で、`If-None-Match` を送ると、変わっていなければ 304 を返します * メンテナンス中は、他の経路と同じく 503 になります `/rest/v1/tools` の各ツールは、`name`・`title`（日本語の名前）・`description`・`scopes`・`plans`・`methods`・`annotations`・`inputSchema`・`outputSchema` と、プランによる違いがあるときだけ `planDifferences` を持ちます。`methods` は、読み取りのツールなら `["GET","POST"]`、それ以外は `["POST"]` です。 ### プランによる違い（planDifferences） `planDifferences` は、プレミアムの定義と比べた、通常（FREE）・ライト（LIGHT）での違いです。 | 項目 | 内容 | | ------------------- | ------------------------- | | `removedProperties` | そのプランでは受け付けない引数 | | `changedProperties` | そのプランでの定義（許容値・制約・説明が違う引数） | | `required` | 必須の引数が基準と違う場合だけ付く | 
```json
"planDifferences": {
  "FREE": { "removedProperties": ["consoleIds", "includeHistory"] },
  "LIGHT": { "removedProperties": ["includeHistory"] }
}
```
 定義に表れないプランの制約は `planDifferences` に含まれません。たとえば `exportMyData` は、出力するデータの種類ごとに必要なプランが違います。これは各ツールの `description` を参照してください。 ### 定義に表れない決まり 次の決まりは、入力スキーマでは表せません。カタログの `notes` と各ツールの `description` を正とします。 * GET のクエリでは配列をカンマ区切りにし、値を percent-encode する * オブジェクトの引数（`externalId` など）は POST の JSON でしか渡せない * `limit` は 1,000 を超えると 1,000 に丸められ、さらにツールごとの上限が適用される。実際の件数は `effectiveLimit`・`limitReduced` で分かる `description` は MCP と共通の説明に、REST だけ違う点を 1 文足した形です（例: `getGamesBatch` は MCP では 20 件、REST では 100 件）。REST では、足された 1 文と入力スキーマの値を正としてください。 [ツールリファレンス](/developers/tools/)には、ツールの用途・権限・プランを日本語でまとめています。 ## 呼び出し方 ツールは `/rest/v1/{ツール名}` で呼び出します。 | 操作 | メソッド | 引数の渡し方 | | -------- | ------------ | --------------- | | 読み取り | GET または POST | クエリ文字列、または JSON | | 追加・更新・削除 | POST | JSON | * GET のクエリでは、配列をカンマ区切りで渡します。数値と真偽値は入力スキーマに従って変換します * **GET のクエリ値は percent-encode してください。** 日本語を含む値や、オブジェクトの引数（`externalId` など）は POST の JSON のほうが確実です * `fields=`（値なし）は、`fields: []` と同じく最小限の項目だけを返します * 受け付けるメソッドは GET / POST / PUT です。それ以外は 405 を返します ### 例: マイライブラリを取得する 
```bash
curl -H "Authorization: Bearer <APIキー>" \
  "https://game.retrogather.com/rest/v1/getLibrary?page=1&limit=50&fields=game,purchase,memo"
```
 ### 例: ゲームを検索する 
```bash
curl -X POST -H "Authorization: Bearer <APIキー>" \
  -H "Content-Type: application/json" \
  -d '{"query":"どらくえ5","limit":5}' \
  https://game.retrogather.com/rest/v1/searchGames
```
 結果の各ゲームは `gameId` を持ちます。追加や更新ではこの `gameId` を使います。 ### 例: マイライブラリに追加する 
```bash
curl -X POST -H "Authorization: Bearer <APIキー>" \
  -H "Content-Type: application/json" \
  -d '{"gameId":1234,"buyDate":"2026-09-20","buyPrice":1500,"buyPlace":"近所の中古ショップ"}' \
  https://game.retrogather.com/rest/v1/addToLibrary
```
 ウィッシュリストにあるゲームを追加すると、ウィッシュリストから外れます。 ### 例: マイコレクションのゲームを置き換える 集合を置き換える操作では、読み取り時の `revision` を送ります。 
```json
{
  "collectionId": "対象のID",
  "gameIds": [1010001, 1010002],
  "revision": "getCollections で取得した値"
}
```
 `POST /rest/v1/updateCollection` の本文の例です。`revision` が合わない場合は拒否されるので、取得し直してから組み立て直してください。 ### 例: 削除する 削除は 2 回の呼び出しで実行します。 1 回目は何も変更せず、確認の情報を返します。 
```bash
curl -X POST -H "Authorization: Bearer <APIキー>" \
  -H "Content-Type: application/json" \
  -d '{"gameId":1234}' \
  https://game.retrogather.com/rest/v1/removeFromWishlist
```
 応答の `summary` に削除する対象と影響、`confirmToken` に確認用のトークンが入ります。利用者の同意を得たら、同じ引数に `confirmToken` を加えて送ります。 
```bash
curl -X POST -H "Authorization: Bearer <APIキー>" \
  -H "Content-Type: application/json" \
  -d '{"gameId":1234,"confirmToken":"1回目の応答の値"}' \
  https://game.retrogather.com/rest/v1/removeFromWishlist
```
 削除の権限は、APIキーの発行時に「個別に設定」で選んだ場合だけ付きます。 ## MCP との違い | 項目 | REST API | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | | 応答 | `structuredContent` と同じ内容を JSON の本文で返す。ゲームの情報の値が無い項目は、省略せず `null` で返す | | 外部リンク | 完成した URL ではなく、外部サービスの ID で返す。専門 wiki などのリンクは返さない。IGDB の ID は[IGDB の識別子](#igdb-%E3%81%AE%E8%AD%98%E5%88%A5%E5%AD%90)を参照 | | `getGamesBatch` | `gameIds` は 1 回 100 件まで（MCP は 20 件）。MCP と上限が違うのはこの引数だけで、ゲームタグ・マイコレクションの `gameIds` / `excludeGameIds` は MCP と同じ上限（マイコレクションは 1,000 件、ゲームタグは 1 タグ 1,000 件） | | `limit` | 1 未満や整数以外は 400。1,000 を超える値は 1,000 に丸め、さらにツールごとの上限を適用する | | ファイル出力 | `exportMyData`・`exportMasterData` は REST API だけで使える。MCP のツール一覧には出ない | ### IGDB の識別子 ゲームの応答（マイライブラリなどの一覧に含まれるゲームも）には、`igdbId` に加えて `igdbSlug` と `igdbCoverId` が入ります。この 2 つは `fields` の指定に関係なく常に返し、値が無い場合は `null` です。カスタムゲームの `igdbSlug` は常に `null` です。MCP はこれらの ID を返さず、完成した URL（`externalLinks`）だけを返します。 | 項目 | URL の組み立て方 | | ------------- | ------------------------------------------------------------------------------------ | | `igdbSlug` | IGDB のゲームページ `https://www.igdb.com/games/{igdbSlug}` | | `igdbCoverId` | IGDB の表紙画像 `https://images.igdb.com/igdb/image/upload/t_cover_big/{igdbCoverId}.jpg` | IGDB のページと画像には、IGDB の規約が適用されます。 ## エラー 入口のエラー（認証・経路）は `error` キー、ツールのエラーは `code` と `message` を持つ JSON を返します。 | 状況 | HTTP | | -------------------- | ---- | | 認証に失敗した | 401 | | 権限またはプランが足りない | 403 | | 対象やツールが無い | 404 | | すでに登録されている | 409 | | `revision` が合わない（競合） | 409 | | 入力が不正 | 400 | | 本文が JSON として読めない | 400 | | 利用上限に達した | 429 | | 一時的に利用できない | 503 | | 想定外のエラー | 500 | * 409 は登録済み（`already_exists`）と競合（`revision_conflict`）の両方で返ります。HTTP ステータスだけで判断せず、`code` で区別してください。競合の場合は最新の状態を取得し直し、更新内容を組み直してから送ります * 削除の確認中に対象が変わった場合は、エラーではなく新しい確認（`confirmToken`）を返します * 429 と 503 では `Retry-After` に従ってください * `retryable` が返る場合は、その値で再試行するかを判断します。`retryable: true` なら同じ呼び出しを再試行できます * 500 のエラーは再試行しても直りません。問い合わせの際は `requestId` を添えてください ### 保存済みのエラー `saved: true` を含むエラーは、保存は完了しています。同じ追加を送り直さず、返された ID や結果を使ってください。応答が失われた場合も、読み取りで状態を確かめてから再送するかを決めてください。詳しくは[エラーの後の確認](/developers/overview/#%E3%82%A8%E3%83%A9%E3%83%BC%E3%81%AE%E5%BE%8C%E3%81%AE%E7%A2%BA%E8%AA%8D)を参照してください。 ## ファイル出力 ファイル出力は REST API だけで使えます。MCP のツール一覧には含まれません。 | ツール | 内容 | 形式 | プラン | | ------------------ | --------------------------------------- | ---------- | ----- | | `exportMyData` | 自分のマイライブラリ・ウィッシュリスト・プレイ記録などの一覧 | CSV / JSON | 全プラン | | `exportMasterData` | ゲームマスタ（プラットフォーム別のゲーム、プラットフォーム、発売元、ジャンル） | NDJSON | プレミアム | どちらもファイルの本文ではなく、ダウンロード用の URL を返します。 * URL の有効期限は 15 分です * **期限内は、URL を持っていれば誰でもダウンロードできます。** URL を共有しないでください * ダウンロードも利用上限を消費します。本文を返せなかった場合は、消費した分を戻します * 実際の列は、応答の `columns` で確認してください。値が無い列は `null` です アプリのゲーム検索から出力する「ゲーム一覧のエクスポート」（CSV / JSON）とは別の機能です。 ### exportMyData `dataset` で出力するデータの種類を選びます。種類によって必要なプランが違います（ゲームタグとゲーム機はライト以上、マイコレクションとカスタムゲームはプレミアム）。マイライブラリ・ウィッシュリスト・プレイ記録・マイコレクション・ゲーム機は、対応する一覧のツールと同じ条件と並び順を指定できます。 ### exportMasterData `dataset`（必須）で対象を選びます。本文はすべて NDJSON です。 | `dataset` | 内容 | 並び順 | | ----------- | -------------------------------------------------- | ----------------------- | | `games` | `platformId` で指定した 1 つのプラットフォームのゲーム（自分のカスタムゲームを含む） | 発売日の昇順（同じ日は `gameId` 順） | | `platforms` | すべてのプラットフォーム | `platformId` 順 | | `companies` | すべての発売元 | `companyId` 順 | | `genres` | 主ジャンルのすべて | `genreId` 順 | * `games` では `platformId` が必須です。指定できるのは公式のプラットフォームだけで、カスタムプラットフォームは `not_found` になります。カスタムゲームは `exportMyData` の `customGames` で出力します * `games` 以外の `dataset` では、`platformId` を受け付けません * ゲームの行は、プラットフォーム・ジャンル・発売元を ID（`platformId`・`genreId`・`publisherId`）と名前の両方で持ちます。ID で `platforms`・`genres`・`companies` のファイルと突き合わせられます * ゲームの行には、JAN コードと外部サービスの ID（`mediaId`・`gpsId`・`igdbId`・`igdbSlug`・`igdbCoverId`）が入ります * `genres` は主ジャンルだけです。ゲームの `genreId` は主ジャンルを指します * `platforms`・`companies` には、プレミアムプランで登録した自分のカスタムプラットフォーム・カスタム発売元が `custom: true` で入ります * ゲームのダウンロードは、`platforms`・`companies`・`genres` のダウンロードより多く利用上限を消費します 応答は `url`・`dataset`・`generation`・`totalCount`・`expiresInSec`・`expiresAt`・`columns` です（`games` は `platformId` も）。`generation` はデータの世代で、前回の応答と同じなら取り直す必要はありません。 ## 利用条件 取得したデータは、アプリ・ツール・サイトへの組み込みを含めて会員本人が利用できます。組み込む場合は、データの出典が Retro Game Gather であることを明示してください。ダウンロードしたファイルそのもの、またはそれと実質的に同じ一覧を配布・公開することは、出典を明記した場合も含めて禁止しています。この条件の対象は Retro Game Gather が提供するゲームデータで、自分で登録した記録とカスタムデータは対象になりません。スクレイピングや大量取得、利用上限を回避する行為は利用停止の対象です。 条件の全体は[MCP / API の仕様の利用条件](/developers/overview/#%E5%88%A9%E7%94%A8%E6%9D%A1%E4%BB%B6)と[利用規約](https://retrogather.com/terms/)を参照してください。

# ツールリファレンス

> Retro Game Gather の REST API で使える 66 のツール（MCP は 64）の用途・必要な権限・対応プラン

MCP と REST API で使えるツールの一覧です。名前は MCP のツール名と REST のパス（`/rest/v1/{ツール名}`）で共通です。 REST API は 66 のツール（通常 31 / ライト 45 / プレミアム 66）を提供します。MCP はそのうち[ファイル出力](#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%87%BA%E5%8A%9B)の 2 つを除く 64 のツール（通常 30 / ライト 44 / プレミアム 64）です。 引数と応答の詳細は、[API リファレンス](/developers/api/)を参照してください。REST の公開カタログ（`GET /rest/v1/tools`・`GET /rest/v1/openapi.json`）から生成しており、プレミアムプランを基準にしています。プランによる引数の違いは、[REST API](/developers/rest-api/#%E3%83%97%E3%83%A9%E3%83%B3%E3%81%AB%E3%82%88%E3%82%8B%E9%81%95%E3%81%84plandifferences)を参照してください。MCP では `tools/list` が、利用者のプランで使える引数を返します。 プランの列は、そのツールを使えるプランです。「全」は通常・ライト・プレミアムのすべてです。 ## アカウント | ツール | 用途 | 権限 | プラン | | ------------ | ----------------------- | ---------- | --- | | `getAccount` | プラン、登録件数と上限、今日の使用率を取得する | いずれかの read | 全 | ## ゲーム情報 | ツール | 用途 | 権限 | プラン | | ------------------ | ------------------------------------ | ----------------------------- | --------------- | | `searchGames` | タイトル・JAN・型番・外部 ID でゲームを特定する（最大 20 件） | `games:read` | 全 | | `searchGamesBatch` | 最大 20 行をまとめて特定する | `games:read` | 全 | | `getGameDetail` | 1 件のゲームの詳細を取得する | `games:read` | 全 | | `getGamesBatch` | 複数のゲームの詳細を取得する | `games:read` | 全 | | `browseGames` | プラットフォーム・ジャンル・発売日などの条件だけでゲームを探す | `games:read` | PREMIUM | | `browseTagGames` | ゲームタグに含まれるゲームを探す | `games:read` + `library:read` | LIGHT / PREMIUM | | `listPlatforms` | プラットフォームの一覧と ID を取得する | `games:read` | 全 | | `listGenres` | ジャンルの一覧と ID を取得する | `games:read` | 全 | | `listCompanies` | 発売元の一覧と ID を取得する | `games:read` | 全 | | `searchNews` | ニュースを検索する | `games:read` | 全 | ## マイライブラリ・ウィッシュリスト | ツール | 用途 | 権限 | プラン | | --------------------- | --------------------------------- | ------------------------------ | --- | | `getLibrary` | マイライブラリの一覧を取得する | `library:read` | 全 | | `addToLibrary` | マイライブラリに追加する（ウィッシュリストにあれば移動する） | `library:write` | 全 | | `addToLibraryBatch` | マイライブラリに最大 100 件をまとめて追加する（試し実行あり） | `library:write` | 全 | | `updateLibraryEntry` | マイライブラリの登録内容を更新する | `library:write` | 全 | | `removeFromLibrary` | マイライブラリから削除する（プレイ記録・所有ソフトも削除） | `library:delete` | 全 | | `getWishlist` | ウィッシュリストの一覧を取得する | `library:read` | 全 | | `addToWishlist` | ウィッシュリストに追加する | `library:write` | 全 | | `updateWishlistEntry` | ウィッシュリストの登録内容を更新する | `library:write` | 全 | | `removeFromWishlist` | ウィッシュリストから削除する | `library:delete` | 全 | | `listAttributes` | マイライブラリ・ウィッシュリスト・プレイ記録の属性の一覧を取得する | `library:read` または `play:read` | 全 | | `getLibraryAnalytics` | マイライブラリを集計する（件数・評価・プラットフォーム・購入） | `library:read` | 全 | ## 所有ソフト | ツール | 用途 | 権限 | プラン | | -------------------- | ------------------------------ | ---------------- | ------- | | `getPhysicalCopies` | 1 件のゲームの所有ソフトを取得する | `library:read` | PREMIUM | | `addPhysicalCopy` | 所有ソフトを追加する（今の 1 本の明細化、または買い足し） | `library:write` | PREMIUM | | `updatePhysicalCopy` | 所有ソフトを更新する、代表の 1 本を切り替える | `library:write` | PREMIUM | | `removePhysicalCopy` | 所有ソフトを削除する | `library:delete` | PREMIUM | ## プレイ記録 | ツール | 用途 | 権限 | プラン | | -------------------- | ---------------------------- | ------------- | ------- | | `getPlayRecords` | ゲームごとの最新のプレイ記録を取得する | `play:read` | 全 | | `addPlayRecord` | プレイ記録を作る、再プレイを始める | `play:write` | 全 | | `updatePlayRecord` | 状態・日付・評価などを更新する | `play:write` | 全 | | `removePlayRecord` | プレイ記録を削除する（プレイログも削除） | `play:delete` | 全 | | `getPlayLogs` | プレイ記録のプレイログを取得する | `play:read` | 全 | | `addPlayLog` | プレイログを追加する | `play:write` | 全 | | `updatePlayLog` | プレイログを更新する | `play:write` | 全 | | `removePlayLog` | プレイログを削除する | `play:delete` | 全 | | `getGamePlayHistory` | 1 件のゲームの過去のプレイ記録を取得する | `play:read` | PREMIUM | | `getPlayAnalytics` | プレイ記録を集計する（状態・月別・プレイ時間の推移など） | `play:read` | 全 | ## カレンダー | ツール | 用途 | 権限 | プラン | | ------------------- | ------------------------------------ | ------------------------------ | --- | | `getCalendarEvents` | 1 か月分の購入・購入予定・プレイ開始・クリアなどの予定と記録を取得する | `library:read` または `play:read` | 全 | ## ゲームタグ | ツール | 用途 | 権限 | プラン | | ---------------- | ---------------------- | ---------------- | --------------- | | `getTags` | ゲームタグの一覧を取得する | `library:read` | LIGHT / PREMIUM | | `addTag` | ゲームタグを作る | `library:write` | LIGHT / PREMIUM | | `updateTag` | ゲームタグの名前・色・説明を更新する | `library:write` | LIGHT / PREMIUM | | `updateTagGames` | ゲームタグのゲームを追加・削除・置き換えする | `library:write` | LIGHT / PREMIUM | | `removeTag` | ゲームタグを削除する | `library:delete` | LIGHT / PREMIUM | ## マイコレクション | ツール | 用途 | 権限 | プラン | | -------------------- | ---------------------- | ---------------- | ------- | | `getCollections` | マイコレクションの一覧を取得する | `library:read` | PREMIUM | | `getCollectionGames` | マイコレクションのゲームと達成状況を取得する | `library:read` | PREMIUM | | `addCollection` | マイコレクションを作る | `library:write` | PREMIUM | | `updateCollection` | マイコレクションを更新する | `library:write` | PREMIUM | | `removeCollection` | マイコレクションを削除する | `library:delete` | PREMIUM | ## ゲーム機 | ツール | 用途 | 権限 | プラン | | ----------------------------- | ---------------------- | ------------- | --------------- | | `getConsoles` | ゲーム機の一覧を取得する | `play:read` | LIGHT / PREMIUM | | `addConsole` | ゲーム機を登録する | `play:write` | LIGHT / PREMIUM | | `updateConsole` | ゲーム機を更新する | `play:write` | LIGHT / PREMIUM | | `removeConsole` | ゲーム機を削除する（メンテナンス記録も削除） | `play:delete` | LIGHT / PREMIUM | | `getConsoleMaintenanceLogs` | メンテナンス記録を取得する | `play:read` | LIGHT / PREMIUM | | `addConsoleMaintenanceLog` | メンテナンス記録を追加する | `play:write` | LIGHT / PREMIUM | | `updateConsoleMaintenanceLog` | メンテナンス記録を更新する | `play:write` | LIGHT / PREMIUM | | `removeConsoleMaintenanceLog` | メンテナンス記録を削除する | `play:delete` | LIGHT / PREMIUM | ## カスタムデータ ゲームデータ管理で登録する、利用者自身のプラットフォーム・発売元・ゲームです。RGG の公式データは変更できません。カスタムデータの閲覧は `games:read` で、ゲーム情報の検索・一覧に含まれます。 | ツール | 用途 | 権限 | プラン | | ---------------------- | ------------- | -------------- | ------- | | `addCustomPlatform` | プラットフォームを追加する | `games:write` | PREMIUM | | `updateCustomPlatform` | プラットフォームを更新する | `games:write` | PREMIUM | | `removeCustomPlatform` | プラットフォームを削除する | `games:delete` | PREMIUM | | `addCustomCompany` | 発売元を追加する | `games:write` | PREMIUM | | `updateCustomCompany` | 発売元を更新する | `games:write` | PREMIUM | | `removeCustomCompany` | 発売元を削除する | `games:delete` | PREMIUM | | `addCustomGame` | ゲームを追加する | `games:write` | PREMIUM | | `updateCustomGame` | ゲームを更新する | `games:write` | PREMIUM | | `removeCustomGame` | ゲームを削除する | `games:delete` | PREMIUM | ## ファイル出力 REST API だけで使えます。MCP のツール一覧には含まれません。 | ツール | 用途 | 権限 | プラン | | ------------------ | -------------------------------------------------------- | ----------------------------------------------------- | ------- | | `exportMyData` | 自分のデータ（マイライブラリ・プレイ記録など）のダウンロード URL を発行する | 対象の read（`library:read` / `play:read` / `games:read`） | 全 | | `exportMasterData` | ゲームマスタ（プラットフォーム別のゲーム、プラットフォーム、発売元、ジャンル）のダウンロード URL を発行する | `games:bulk` | PREMIUM | `exportMyData` で出力できるデータの種類はプランによって異なります。ゲームタグとゲーム機はライト以上、マイコレクションとカスタムゲームはプレミアムです。詳しくは[REST API のファイル出力](/developers/rest-api/#%E3%83%95%E3%82%A1%E3%82%A4%E3%83%AB%E5%87%BA%E5%8A%9B)を参照してください。 ## 削除の確認が必要なツール 名前が `remove` で始まるツールは、2 回の呼び出しで削除します。FREE / LIGHT の再プレイ（`addPlayRecord` の `replay: true`）も、直前のプレイ記録とプレイログを置き換えるため、同じ確認が必要です。手順は[削除の確認](/developers/overview/#%E5%89%8A%E9%99%A4%E3%81%AE%E7%A2%BA%E8%AA%8D)を参照してください。