Skip to main content
Glama
mcp-graphql-bridge

mcp-graphql-bridge

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 エクスプローラーツールを登録します

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: 環境変数の設定

変数

必須

説明

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)

Available Tools

2 tools
execute_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

    A3.9/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools serve clearly distinct purposes: executing GraphQL operations vs. retrieving type metadata. No overlap in functionality.

    Naming Consistency5/5

    Both tool names follow a consistent verb_noun pattern using snake_case (execute_graphql, get_type_details), making the intent clear and predictable.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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 context
      46
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      A Model Context Protocol server that enables LLMs to interact with GraphQL APIs by providing schema introspection and query execution capabilities.
      3
      MIT