mcp-graphql-bridge
mcp-graphql-bridge
あらゆるGraphQL APIをClaude Codeに接続するための汎用的なMCP(Model Context Protocol)サーバーです。GraphQLスキーマをイントロスペクションし、各クエリとミューテーションを個別のツールとして公開することで、Claudeが直接APIとやり取りできるようにします。
仕組み
サーバーは起動時に以下の処理を行います:
作業ディレクトリ内の
schema-introspection.jsonファイルを探します(高速で、ネットワーク呼び出しは発生しません)ファイルが見つからない場合、
GRAPHQL_INTROSPECTION_URLに対してライブイントロスペクションを実行しますクエリごとに1つ(
query__<name>)、ミューテーションごとに1つ(mutation__<name>)のツールを登録します常に汎用的な
execute_graphqlフォールバックツールと、get_type_detailsエクスプローラーツールを登録します
Related MCP server: GraphQL MCP Server
要件
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: 環境変数の設定
変数 | 必須 | 説明 |
| はい | クエリとミューテーションに使用するエンドポイント |
| はい | スキーマイントロスペクションに使用するエンドポイント(上記と同じでも可) |
| はい | 認証用の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.jsonClaude 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 を実行し、利用可能なサーバーとツールを確認します。
利用可能なツール
ツール | 説明 |
| GraphQLクエリフィールドごとに1つのツール |
| GraphQLミューテーションフィールドごとに1つのツール |
| 汎用フォールバック — 任意のクエリやミューテーションを実行 |
| 特定の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
修正方法:
npm run buildを実行したことを確認します(dist/フォルダが作成されます)MCP設定を更新し、
/dist/index.jsで終わるフルパスを使用します
スキーマイントロスペクションの失敗
サーバーは起動するが「Schema introspection failed」と表示される場合、GraphQL APIの本番環境でイントロスペクションが無効になっている可能性があります。セットアップのステップ3にあるcurlコマンドを使用して、schema-introspection.json ファイルを事前生成してください。
ツールがClaude Codeに表示されない
claude mcp listを実行して、サーバーが登録されているか確認しますClaude Codeセッションで
/mcpを実行して、利用可能なツールを確認します必要な環境変数がすべて設定されているか確認します(
GRAPHQL_API_URL,GRAPHQL_INTROSPECTION_URL,GRAPHQL_TOKEN)
Available Tools
2 toolsexecute_graphqlA
Execute any GraphQL query or mutation against the API. Use this when no specific tool exists for your operation.
Inputs: query (required), variables, bearer_token, custom_headers.
get_type_detailsB
Get fields of a specific GraphQL type to know what to put in __fields
Inputs: typeName (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 2 tools
The two tools serve clearly distinct purposes: executing GraphQL operations vs. retrieving type metadata. No overlap in functionality.
Both tool names follow a consistent verb_noun pattern using snake_case (execute_graphql, get_type_details), making the intent clear and predictable.
For a GraphQL bridge, two tools is minimal but still covers the essential operations of executing queries and exploring types. Slightly under-scoped but reasonable.
The tool surface covers core GraphQL operations (any query/mutation) and type introspection. Minor gaps exist (e.g., no dedicated tool for listing mutations), but the generic execute tool and type details suffice for agents familiar with GraphQL.
Maintenance
Related MCP Connectors
The Grafbase MCP server sits in front of a GraphQL API and exposes an MCP protocol-compliant interface that allows AI agents and LLMs to explore and query GraphQL APIs using natural language. It provides tools to search schemas, introspect types and fields, and execute GraphQL queries while minimizing context bloat by returning only relevant schema subsets, with built-in support for authentication, authorization, and configurable access control.
An MCP server that provides an API to LLMs to manage their JumpCloud resources.
Talk to your public-facing AI from any MCP client — Claude, ChatGPT, Cursor, Cline, Windsurf.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA MCP server that exposes GraphQL schema information to LLMs like Claude. This server allows an LLM to explore and understand large GraphQL schemas through a set of specialized tools, without needing to load the whole schema into the context46MIT
- AlicenseCqualityDmaintenanceA TypeScript server that provides Claude AI with seamless access to any GraphQL API through the Model Context Protocol.616 npm12MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLMs to interact with GraphQL APIs by providing schema introspection and query execution capabilities.3MIT
- AlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that enables LLMs to interact with GraphQL APIs by providing schema introspection and query execution capabilities.MIT