Skip to main content
Glama
deenesjakoruzh
murilojrpereira

mcp-graphql-bridge

by murilojrpereira
OverviewSchemaRelated ServersScoreDiscussions
JavaScript
Remote

mcp-graphql-bridge

npm version CI License: MIT Node.js >= 18

あらゆる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 >= 18

セットアップ

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

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

npm install -g mcp-graphql-bridge

オプション B: クローンしてソースからビルド

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

ステップ 2: 環境変数の設定

変数

必須

説明

GRAPHQL_API_URL

はい

クエリとミューテーションに使用するエンドポイント

GRAPHQL_INTROSPECTION_URL

はい

スキーマイントロスペクションに使用するエンドポイント（上記と同じでも可）

GRAPHQL_TOKEN

はい

認証用のBearerトークン

これらはプロジェクトルートの .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のイントロスペクションが無効になっている場合や、起動時間を短縮したい場合にのみ使用してください：

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 } } } } } type { 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 } } } } } type { kind name ofType { kind name ofType { kind name } } } } } } }"}' \
  > schema-introspection.json

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 を実行し、利用可能なサーバーとツールを確認します。

利用可能なツール

ツール

説明

query__<name>

GraphQLクエリフィールドごとに1つのツール

mutation__<name>

GraphQLミューテーションフィールドごとに1つのツール

execute_graphql

汎用フォールバック — 任意のクエリやミューテーションを実行

get_type_details

特定のGraphQL型のフィールドを探索

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

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

注意: -i フラグ（-t なし）が必要です。これにより、MCP stdioプロトコル用に標準入力が開いたままになります。

開発

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

トラブルシューティング

エラー: 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_URL, GRAPHQL_INTROSPECTION_URL, GRAPHQL_TOKEN）

Install Server
A
license - permissive license
A
quality
C
maintenance

How are these scores calculated?

Resources

Tools

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/murilojrpereira/mcp-graphql-bridge'

If you have feedback or need assistance with the MCP directory API, please join our Discord server