mcp-graphql-bridge

mcp-graphql-bridge

任意の GraphQL API と Claude Code を橋渡しする汎用 MCP（Model Context Protocol）サーバーです。GraphQL スキーマをイントロスペクションし、各クエリとミューテーションを個別のツールとして公開することで、Claude が API と直接やり取りできるようにします。

動作の仕組み

起動時にサーバーは次の処理を行います。

1. 作業ディレクトリ内で schema-introspection.json ファイルを探します（高速で、ネットワーク呼び出しは不要です）
2. 見つからない場合は、GRAPHQL_INTROSPECTION_URL に対してライブイントロスペクションを実行します
3. クエリごとに 1 つのツール（query__<name>）、ミューテーションごとに 1 つのツール（mutation__<name>）を登録します
4. 汎用のフォールバックツール execute_graphql と、探索用ツール get_type_details を常に登録します

要件

• Node.js >= 20

セットアップ

ステップ 1：インストール

オプション A：npm からインストール（推奨）

npm install -g mcp-graphql-bridge

オプション B：ソースをクローンしてビルド

git clone https://github.com/murilojrpereira/mcp-graphql-bridge.git
cd mcp-graphql-bridge
npm install
npm run build

ステップ 2：環境変数を設定

変数	必須	説明
GRAPHQL_API_URL	いいえ	クエリとミューテーションに使用するエンドポイントです。設定されていない場合は、公開デモ API（countries.trevorblades.com）が既定値になります。実際の用途では独自のエンドポイントに置き換えてください。
GRAPHQL_INTROSPECTION_URL	いいえ	スキーマのイントロスペクションに使用するエンドポイントです。設定されていない場合は、GRAPHQL_API_URL が既定値になります。
GRAPHQL_TOKEN	いいえ	GraphQL 認証用のベアラートークンです（クエリ／ミューテーションの実行に使用）。公開 API では省略してください。
GRAPHQL_INTROSPECTION_TOKEN	いいえ	実行時とは異なる認証情報が必要な場合（例：別のスキーマレジストリ）に使う、スキーマイントロスペクション用のベアラートークンです。設定されていない場合は、GRAPHQL_TOKEN が既定値になります。
MCP_AUTH_TOKEN	いいえ	MCP_TRANSPORT=http のとき、ホストされる /mcp HTTP エンドポイントで必要となるベアラートークンです
GRAPHQL_MAX_TOOLS	いいえ	登録するクエリ／ミューテーションツールの最大数です。上限に達した場合、ミューテーションよりクエリが優先されます。既定値は 128 です。
GRAPHQL_INCLUDE_MUTATIONS	いいえ	読み取り専用で運用する場合は false に設定すると、すべてのミューテーションフィールドを除外します。既定値は true です。
GRAPHQL_MAX_RETRIES	いいえ	429／502／503／504 応答に対する再試行回数（0～5）です。Retry-After がある場合はそれに従います。既定値は 0（無効）です。

数百のフィールドを持つスキーマ（GitHub の GraphQL API にはルートフィールドが 284 個あり、クエリが 32 個、ミューテーションが 252 個あります）では、GRAPHQL_MAX_TOOLS と GRAPHQL_INCLUDE_MUTATIONS によって、登録数を制限し、予測可能にできます。上限によってスキーマが切り詰められた場合、登録されたクエリ／ミューテーション数と利用可能な数が stderr に正確に記録されます。

サーバーを試すのに設定は不要です。何も設定しない場合、上記の公開デモ API に対して起動し、その旨をログに記録します。トークンの完全なモデルと、GraphQL エンドポイントをリクエストごとのパラメーターではなくデプロイごとに固定する理由については、docs/architecture.md を参照してください。

プロジェクトのルートにある .env ファイルに設定できます。

GRAPHQL_API_URL=https://your-api.example.com/graphql
GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql
GRAPHQL_TOKEN=your-bearer-token

または、claude mcp add コマンドで直接渡すこともできます（下記を参照してください）。

ステップ 3：（任意）スキーマスナップショットを事前生成する

デフォルトでは、サーバーは起動時にスキーマをライブでイントロスペクションします。ファイルは不要で、API が最大深度での試行を拒否した場合（特に CDN を経由する API の一部では、クエリ深度の上限が設定されています）も、より浅いクエリ深度で自動的に再試行します。本番環境で API のイントロスペクションが完全に無効になっている場合、または起動を高速化したい場合にのみ、この手順を使用してください。

curl -s -X POST https://your-api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-bearer-token" \
  -d '{"query":"{ __schema { queryType { fields { name description args { name description defaultValue type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } } } } type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } } } } } mutationType { fields { name description args { name description defaultValue type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } } } } type { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name ofType { kind name } } } } } } } } } } }"}' \
  > schema-introspection.json

API が深度／複雑度の上限エラーでこれを拒否する場合は、ofType { ... } のネストを浅くしてください（各レベルで NonNull／List のラッパーをさらに 1 つ解決します。実際の多くの型では 2～3 レベルが必要です。[[Int!]!]! のように二重にラップされたリストのみ、さらに深いネストが必要です）。

Claude Code への追加

オプション A：ユーザースコープ（自分専用）

npm からインストールした場合：

claude mcp add --transport stdio \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- mcp-graphql-bridge

ソースからクローンした場合：

claude mcp add --transport stdio \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- node /absolute/path/to/mcp-graphql-bridge/dist/index.js

重要： mcp-graphql-bridge/index.js ではなく、コンパイル済みの出力である mcp-graphql-bridge/dist/index.js を使用してください。TypeScript ソースは事前に npm run build でビルドする必要があり、エントリーポイントは dist/ フォルダーにあります。

オプション B：プロジェクトスコープ（.mcp.json を介してチームと共有）

claude mcp add --transport stdio --scope project \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- mcp-graphql-bridge

注： 絶対パスを使用してください。すべての --env フラグと --transport フラグは、サーバー名より前に指定する必要があります。

接続を確認する

claude mcp list

その後、Claude Code のセッションで /mcp を実行すると、利用可能なサーバーとツールを確認できます。

MCP レジストリ

このサーバーは、公式の MCP レジストリ に io.github.murilojrpereira/mcp-graphql-bridge として公開されています。そのため、レジストリを参照する MCP クライアントは、ここから見つけてインストールできます。

例

設定不要の小規模な公開スキーマと、認証およびツール数の制限が必要な、実際の大規模なエンタープライズスケールのスキーマを順に紹介する、2 つの詳しいチュートリアルです。

例 1：Countries API（小規模なスキーマ、認証なし）

これは設定不要のデフォルト構成です。サーバー本体以外に、インストールや設定は必要ありません。

1. 環境変数を一切指定せずにサーバーを追加します。

   claude mcp add --transport stdio graphql-countries -- mcp-graphql-bridge
   

2. Claude Code を再起動します（または /mcp を実行して graphql-countries が接続されていることを確認します）。query__country、query__countries、query__continents などのツールが表示されます。

3. Claude に依頼します。

   graphql-countries を使って、コードが「BR」の国を見つけ、その国の大陸にあるほかの国を一覧表示してください。

   Claude は query__country({ code: "BR", __fields: "{ name continent { code name } }" }) を呼び出し、 続いて結果に基づいて query__continent または query__countries({ __fields: "{ name }" }) を呼び出します。

4. 無効なコードを指定して、エラーがそのまま返されることを確認します。

   コードが「ZZZ」の国を検索してください。

   GraphQL API 自身のエラーテキストが返されます。ブリッジはエラーを隠さず、そのまま渡します。

例 2：GitHub GraphQL API（大規模なスキーマ、認証とツール数の制限）

GitHub の GraphQL API には 284 個のルートフィールド（クエリ 32 個、ミューテーション 252 個）があり、デフォルトの GRAPHQL_MAX_TOOLS である 128 を大きく上回ります。また、一部の読み取りを匿名で許可する GitHub の REST API とは異なり、イントロスペクションを含むすべてのリクエストでトークンが必要です。

1. 読み取り専用のアクセス範囲でサーバーを追加します。

   export GH_TOKEN=ghp_your_personal_access_token  # or: source a gitignored .env file first
   
   claude mcp add --transport stdio graphql-github \
     --env GRAPHQL_API_URL=https://api.github.com/graphql \
     --env GRAPHQL_INTROSPECTION_URL=https://api.github.com/graphql \
     --env GRAPHQL_TOKEN=$GH_TOKEN \
     --env GRAPHQL_INCLUDE_MUTATIONS=false \
     graphql-bridge -- mcp-graphql-bridge
   

   GRAPHQL_INCLUDE_MUTATIONS=false を指定すると、読み取り専用のクエリ 32 個がすべて登録され、ミューテーションは登録されません。上限を十分に下回り、252 個すべての書き込み操作を公開するよりも、AI エージェントにとって実質的に安全なデフォルト設定です。

2. Claude に依頼します。

   graphql-github を使って facebook/react リポジトリを検索し、スター数を教えてください。

   Claude は query__repository({ owner: "facebook", name: "react", __fields: "{ name stargazerCount }" }) を呼び出します。

3. ミューテーションも利用するには、GRAPHQL_INCLUDE_MUTATIONS=false を削除し、上限を引き上げます（GRAPHQL_MAX_TOOLS=400）。この設定では、トークンに設定された権限の範囲内で、GitHub アカウントへの書き込みアクセスが公開される点に注意してください。

利用可能なツール

ツール	説明
query__<name>	GraphQL クエリフィールドごとに 1 つのツール
mutation__<name>	GraphQL ミューテーションフィールドごとに 1 つのツール
execute_graphql	汎用フォールバック — 任意のクエリまたはミューテーションを実行します（GRAPHQL_INCLUDE_MUTATIONS=false の場合、ミューテーションは拒否されます）
get_type_details	特定の GraphQL 型のフィールドを調べます

すべての操作別ツールは、カスタム GraphQL 選択セット（例：{ id name status }）を指定できる特別な __fields 引数を受け付けます。省略した場合は、スカラー型のフィールドのみが返されます。

呼び出しごとの認証情報の上書き：execute_graphql を含むすべてのツールは、bearer_token および custom_headers 引数も受け付けます。指定すると、その 1 回のリクエストに限り GRAPHQL_TOKEN／認証なしの設定が上書きされるため、サーバーを再起動せずに Claude が呼び出しごとに認証情報を切り替えられます。

セキュリティ

• 接続先 API はデプロイごとに固定され、リクエストごとのパラメーターにはできません。 個々のツール呼び出しでは 認証情報（bearer_token、custom_headers）を上書きできますが、接続先ホストは変更できません。 GRAPHQL_API_URL はデプロイ時に一度設定されます。呼び出し元が任意の接続先にリダイレクトできる共有サーバーは、 サーバーサイドリクエストフォージェリ（SSRF）の脆弱性につながります。この設計では、その可能性を構造上排除しています。
• 設定済みのシークレットと呼び出しごとのシークレットは、呼び出し元の LLM に届く前に、すべてのレスポンスからマスキングされます。
• GRAPHQL_INCLUDE_MUTATIONS=false にすると、すべてのミューテーションフィールドが登録対象から除外され、 真に読み取り専用のデプロイが可能になります。これはトークンのスコープだけに依存するのではなく、 GraphQL の型システムですでに表現されている、実質的な信頼境界です。この制約は execute_graphql にも適用されます。 このフラグがオフの場合、クエリを解析してミューテーションを拒否します。利便性を高める mutation__* ツールだけを除外し、汎用フォールバックでは任意の操作を実行できる状態にはしません。
• MCP_AUTH_TOKEN は、パブリックネットワークからアクセス可能なデプロイで HTTP トランスポートの /mcp エンドポイントを保護します。 リクエストサイズは 10MB までです。

設計の根拠については docs/architecture.md を、 脆弱性の報告については SECURITY.md を参照してください。

Docker

イメージをビルドする

docker build -t mcp-graphql-bridge .

Docker 経由で Claude Code に追加する

claude mcp add --transport stdio \
  --env GRAPHQL_API_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  --env GRAPHQL_TOKEN=your-bearer-token \
  graphql-bridge -- docker run -i --rm \
  -e GRAPHQL_API_URL -e GRAPHQL_INTROSPECTION_URL -e GRAPHQL_TOKEN \
  mcp-graphql-bridge

注記： MCP の stdio プロトコルでは標準入力を開いたままにする必要があるため、-i フラグ（-t なし）が必須です。

HTTP デプロイ

ホスト型の MCP アクセスを利用するには、stdio の代わりに HTTP トランスポートを実行します。

docker build -f Dockerfile.http -t mcp-graphql-bridge-http .
docker run --rm -p 8080:8080 \
  -e GRAPHQL_API_URL=https://your-api.example.com/graphql \
  -e GRAPHQL_INTROSPECTION_URL=https://your-api.example.com/graphql \
  -e GRAPHQL_TOKEN=your-bearer-token \
  mcp-graphql-bridge-http

ヘルスチェックは /health で利用でき、MCP リクエストは /mcp で処理されます。

パブリックネットワークからアクセス可能なデプロイでは、MCP_AUTH_TOKEN を設定し、クライアントが /mcp に Authorization: Bearer <token> を送信するよう設定してください。

AWS、Cloudflare、その他のコンテナーのホスティングオプションについては、docs/deployment.md を参照してください。

開発

npm run dev   # watch mode: rebuilds and restarts on file changes
npm run build # one-off TypeScript compile
npm start     # run the compiled server

貢献のガイドラインとメンテナーによるリリース手順については、CONTRIBUTING.md を参照してください。

トラブルシューティング

エラー：Cannot find module '.../index.js'

次のようなエラーが表示される場合：

Error: Cannot find module '/path/to/mcp-graphql-bridge/index.js'

指定しているファイルが間違っています。TypeScript ソースを先にコンパイルする必要があり、エントリーポイントは dist/ フォルダーにあります。

正しいパス： /path/to/mcp-graphql-bridge/dist/index.js 誤ったパス： /path/to/mcp-graphql-bridge/index.js

修正方法：

1. npm run build を実行したことを確認します（dist/ フォルダーが作成されます）。
2. MCP 設定を更新し、/dist/index.js で終わる完全なパスを指定します。

スキーマのイントロスペクションに失敗する

サーバーは起動するものの「Schema introspection failed」と表示される場合、GraphQL API で本番環境のイントロスペクションが無効になっている可能性があります。セットアップの手順 3 に記載されている curl コマンドを使って、schema-introspection.json ファイルを事前に生成してください。

Claude Code にツールが表示されない場合

1. claude mcp list を実行して、サーバーが登録されていることを確認します
2. Claude Code のセッションで /mcp を実行して、利用可能なツールを確認します
3. GraphQL API の環境変数（GRAPHQL_API_URL、GRAPHQL_INTROSPECTION_URL、GRAPHQL_TOKEN）が正しく設定されていることを確認します。これらは任意で、デフォルトでは公開デモ API が使用されるため、ご自身の API を設定してもツールが表示されない場合は、認証情報とエンドポイント URL を確認してください