あらゆる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
npm install -g mcp-graphql-bridgegit clone https://github.com/murilopereira/mcp-graphql-bridge.git
cd mcp-graphql-bridge
npm install
npm run build変数 | 必須 | 説明 |
| はい | クエリとミューテーションに使用するエンドポイント |
| はい | スキーマイントロスペクションに使用するエンドポイント（上記と同じでも可） |
| はい | 認証用の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 コマンドで直接渡すこともできます（下記参照）。
デフォルトでは、サーバーは起動時にライブでスキーマをイントロスペクションするため、ファイルは不要です。このステップは、本番環境で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.jsonnpmからインストールした場合：
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/フォルダ内にあります。
.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 build -t 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 -- 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以下のようなエラーが表示される場合：
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 mcp list を実行して、サーバーが登録されているか確認します
Claude Codeセッションで /mcp を実行して、利用可能なツールを確認します
必要な環境変数がすべて設定されているか確認します（GRAPHQL_API_URL, GRAPHQL_INTROSPECTION_URL, GRAPHQL_TOKEN）
Execute any GraphQL query or mutation against the API. Use this when no specific tool exists for your operation.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Full GraphQL query or mutation string including selection set | |
| variables | No | Variables for the operation | |
| bearer_token | No | Bearer token to authenticate this request (overrides GRAPHQL_TOKEN) | |
| custom_headers | No | Additional request headers as key-value pairs, e.g. {"X-Tenant-ID": "abc"} |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description must disclose behavioral traits. It does not mention potential side effects of mutations, authentication requirements (beyond parameter hints), rate limits, or error handling. The description is too minimal to convey safe usage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences pack purpose and usage guidelines with zero waste, frontloading the key action and fallback use.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema; description does not explain return format, errors, or the fact that the endpoint is pre-configured. Despite the complexity of a generic GraphQL executor, the description is incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (all 4 parameters have descriptions). The description adds no additional parameter semantics. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Execute any GraphQL query or mutation against the API', specifying the verb and resource. It distinguishes itself from sibling 'get_type_details' by being a generic executor.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use this when no specific tool exists for your operation', providing clear when-to-use guidance. No exclusions, but the instruction is direct.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get fields of a specific GraphQL type to know what to put in __fields
| Name | Required | Description | Default |
|---|---|---|---|
| typeName | Yes | GraphQL type name, e.g. 'Repository', 'User', 'Issue' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must disclose all behavioral traits. It indicates a read operation, but does not mention error handling (e.g., invalid type name), response structure, or any side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, focused sentence with no extraneous text. It is front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Despite the tool's simplicity, the description omits output details. The agent does not know whether the response returns field names, types, or full schema; this is critical given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema already covers the single parameter with a clear description and examples. The tool description adds no extra meaning beyond prompting usage of '__fields'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool gets fields of a specific GraphQL type and its purpose in GraphQL introspection. However, it does not differentiate from sibling tool execute_graphql, which may also retrieve type information.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'to know what to put in __fields' implies a use case, but there is no explicit guidance on when to use this tool versus execute_graphql, nor any when-not-to-use advice.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v2.1.0execute_graphql2 fields changedInput schema / properties / bearer_tokenAdded value: +{
+ "description": "Bearer token to authenticate this request (overrides GRAPHQL_TOKEN)",
+ "type": "string"
+}Input schema / properties / custom_headersAdded value: +{
+ "additionalProperties": {
+ "type": "string"
+ },
+ "description": "Additional request headers as key-value pairs, e.g. {\"X-Tenant-ID\": \"abc\"}",
+ "type": "object"
+}get_type_details1 field changedInput schema / properties / typeName / descriptionPrevious value: -"GraphQL type name, e.g. 'Machine', 'WorkOrder', 'Shift'"New value: +"GraphQL type name, e.g. 'Repository', 'User', 'Issue'"v1.0.1execute_graphqlget_type_detailsScored 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.
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…
