Claude Media
GraphQL MCPサーバーでClaudeにAPIを叩かせる — mcp-graphqlの使い方
Claude CodeMCPClaude連携チュートリアル

GraphQL MCPサーバーでClaudeにAPIを叩かせる — mcp-graphqlの使い方

mcp-graphqlを使ってGraphQL APIをMCPサーバー化し、Claude CodeにスキーマIntrospectionとクエリ実行を任せる手順を、環境変数の設計とMutation許可の判断まで解説します。

読了目安 約12分

GraphQL APIはRESTと違い、1つのエンドポイントの背後にスキーマという「使い方の説明書」を持っています。この構造は、モデルがまずスキーマを調べてからクエリを組み立てるという2段階の動きと相性がよく、GraphQL専用のMCPサーバー実装がいくつも公開されている理由もそこにあります。この記事では代表的なOSS実装mcp-graphqlを使って、GraphQL APIをMCPサーバー化しClaude Codeから叩けるようにする手順を扱います。

MCPプロトコル自体の仕組みはMCPとは、claude mcp addの構文やスコープの詳細はClaude Code MCP設定ガイドが対応します。

mcp-graphqlとは

mcp-graphqlとは、GraphQL APIへのスキーマIntrospectionとクエリ実行をツール化するModel Context Protocolサーバーです。開発者のblurrah氏が公開しているOSS実装で、npmパッケージmcp-graphqlとして配布されています。最新版は2.0.4で、2025年5月に公開されて以降、破壊的な仕様変更は入っていません。

このサーバーが提供するツールは2つだけです。

ツールできること
introspect-schemaできることGraphQLのIntrospectionクエリでスキーマを取得する(ローカルのスキーマファイルやSCHEMAで指定したURLがあればそちらを優先)
query-graphqlできること実際にクエリを実行する。既定ではMutationは無効

スキーマはgraphql-schemaという名前のMCPリソースとしても公開されるため、クライアントによってはツール呼び出し無しにスキーマへアクセスできます。

ツールとリソースの違い

MCPには「ツール」と「リソース」という2つの露出方法があります。ツールはモデルが能動的に呼び出す関数で、リソースはクライアント側が事前に取得しておける静的なコンテキストです。mcp-graphqlはスキーマを両方の形で提供しており、対応クライアントは会話の開始時にリソースとしてスキーマを読み込んでおき、以降はintrospect-schemaツールを呼ばずにquery-graphqlだけでクエリを実行できます。すべてのクライアントがリソースの自動読み込みに対応しているわけではないため、動作が期待と違う場合はまずintrospect-schemaを明示的に呼び出す運用が確実です。

環境変数でエンドポイントと権限を決める

mcp-graphqlはバージョン1.0.0でコマンドライン引数から環境変数に設定方式を切り替えており、現行版ではすべて環境変数で構成します。

環境変数役割既定値
ENDPOINT役割接続先のGraphQLエンドポイントURL既定値http://localhost:4000/graphql
HEADERS役割リクエストヘッダーをJSON文字列で指定(認証トークン等)既定値{}
ALLOW_MUTATIONS役割Mutation操作を許可するか既定値false
SCHEMA役割ローカルのスキーマファイルパスまたはURL(指定するとIntrospectionを省略)既定値未指定
NAME役割MCPサーバーの表示名既定値mcp-graphql

ALLOW_MUTATIONSが既定でfalseになっている点が、このサーバーの設計思想を表しています。読み取り専用から始めて、必要になったら明示的に開ける構成です。

導入手順

Claude Codeへの追加はclaude mcp addで完結します。GraphQLエンドポイントとヘッダーを環境変数として渡します。

claude mcp add --env ENDPOINT=https://api.example.com/graphql \
  --env HEADERS='{"Authorization":"Bearer YOUR_TOKEN"}' \
  --transport stdio graphql -- npx mcp-graphql

ローカルの開発サーバーに繋ぐだけであれば、ENDPOINTのみで十分です。

claude mcp add --env ENDPOINT=http://localhost:3000/graphql --transport stdio graphql -- npx mcp-graphql

Smitheryから導入する場合

サードパーティのMCPサーバー配布サービスSmitheryにも登録されており、CLI経由で導入することもできます。

npx -y @smithery/cli install mcp-graphql --client claude

Smithery経由のインストールは環境変数の入力を対話形式で求められる点がclaude mcp addと異なります。チームで設定を.mcp.jsonにコミットして共有したい場合は、claude mcp addで直接追加する方式のほうが構成をバージョン管理に残しやすくなります。

接続後、Claudeに「利用可能なGraphQLのクエリとタイプを教えて」のように聞くと、introspect-schemaツールが呼ばれてスキーマ全体が返ってきます。以降はそのスキーマをもとに、Claudeがquery-graphqlでクエリ文字列を組み立てて実行します。

複数のGraphQL APIを同時に繋ぐ

社内に複数のGraphQL APIがある場合、claude mcp addを繋ぎたいAPIの数だけ実行し、それぞれ別の名前を付けて登録します。NAME環境変数でMCPサーバー自体の表示名も変えておくと、Claudeが応答の中でどちらのAPIから得た情報かを区別しやすくなります。

claude mcp add --env ENDPOINT=https://users-api.example.com/graphql --env NAME=users-graphql \
  --transport stdio users-graphql -- npx mcp-graphql
claude mcp add --env ENDPOINT=https://billing-api.example.com/graphql --env NAME=billing-graphql \
  --transport stdio billing-graphql -- npx mcp-graphql

サーバーごとにプロセスが独立するため、一方のエンドポイントでALLOW_MUTATIONS=trueにしても、もう一方には影響しません。APIごとに書き込み権限を個別に設計できる点は、単一のMCPサーバーで複数エンドポイントを切り替える設計より安全側に倒しやすい構成です。

Mutationを許可するかどうかの判断

ALLOW_MUTATIONS=trueを付けない限り、Claudeは読み取り専用のクエリしか実行できません。この既定値は、LLMがデータベースや外部サービスの状態を書き換えるリスクを踏まえた安全側の設計です。

Mutationを許可する場合の判断材料は次の3つです。

  • 接続先が本番環境か検証環境か — 検証環境限定でMutationを開け、本番は読み取り専用に留めるという分離が現実的です
  • エンドポイント自体に認可制御があるか — HEADERSで渡すトークンの権限スコープが、GraphQL API側のリゾルバレベルで書き込み範囲を制限しているかを確認します。mcp-graphql自体はクエリ内容を検証しません
  • 意図しないMutationをどこまで許容できるか — スキーマに削除系のMutationが含まれる場合、ALLOW_MUTATIONS=trueは削除操作も同時に許可します。特定のMutationだけを許可する仕組みはサーバー側に無いため、全許可か全禁止かの二択になります

権限設計をMCPツール単位でさらに細かく制御したい場合は、Claude Code側の許可ルールでmcp__graphql__query-graphqlをaskにし、実行のたびに確認を挟む運用も選べます。詳しい書き方はMCPセキュリティガイドを参照してください。

RESTのMCP連携との違い

業務SaaSをMCP経由で自作接続する場合、多くはREST APIをエンドポイントごとにツール化します。GraphQLはこれと発想が異なり、エンドポイントは1つのまま、スキーマの探索とクエリの組み立てをモデルに任せます。

REST APIのMCP化GraphQLのMCP化
ツールの単位REST APIのMCP化エンドポイントごとに個別ツールGraphQLのMCP化introspect-schemaとquery-graphqlの2つで完結
新しいAPIへの追随REST APIのMCP化エンドポイント追加のたびにツール定義を書き直すGraphQLのMCP化スキーマが変われば自動的に追随する
権限の粒度REST APIのMCP化エンドポイント単位で絞りやすいGraphQLのMCP化クエリ/Mutationの二択が基本

エンドポイント単位で権限を絞りたい業務システムはREST寄りのアプローチが向いており、具体的な自作手順は業務SaaS MCP連携ガイドで扱っています。逆に、スキーマの変化が速い社内GraphQL APIや、そもそもREST層を持たないAPIではmcp-graphqlのような汎用実装のほうが保守コストが低くなります。

独自のMCPサーバーを作る選択肢

mcp-graphqlのREADME自身が、これは「非常に汎用的な実装」であり、Introspectionもクエリ実行も丸ごと許可する設計だと明記しています。特定のクエリフィールドや変数だけをクライアントに使わせたい場合は、mcp-graphqlをコード上の参考にしつつ、専用のMCPサーバーを自作するアプローチも選択肢に入ります。

汎用実装をそのまま使うか自作するかの判断は、公開するAPIの性質に依存します。社内ツール向けで利用者を信頼できるならmcp-graphqlで十分ですが、外部公開のAPIや機密性の高いスキーマを扱うなら、ツールの入力スキーマ自体を絞り込んだ専用実装のほうが安全側に倒せます。具体的には、query-graphqlのような汎用クエリ実行ツールを置き換え、あらかじめ用意した固定のクエリ文字列に対して変数だけを受け取るツールを複数用意する設計が考えられます。この方式ならモデルが任意のフィールドを組み合わせてクエリを組み立てる自由度自体が無くなり、意図しないフィールドへのアクセスやN+1的な高コストクエリの生成を構造的に防げます。

よくあるつまずき

Introspectionが無効化されているAPIに繋げない

本番運用のGraphQL APIではセキュリティ上の理由からIntrospectionを無効化していることがよくあります。この場合introspect-schemaツールを呼んでも空のスキーマしか返りません。SCHEMA環境変数でスキーマファイルまたはスキーマを公開しているURLを別途指定する必要があります。

認証ヘッダーのJSON文字列がシェルでエスケープされる

HEADERSはJSON文字列として渡す仕様のため、シェルの引用符処理でクォートが崩れやすい箇所です。claude mcp addのコマンド全体をダブルクォートで囲んでいる場合、内側のJSONのダブルクォートは\"でエスケープする必要があります。.mcp.jsonにサーバー定義を直接書く方式であれば、この問題を避けられます。

Mutationを許可したのにエラーになる

ALLOW_MUTATIONS=trueにしてもMutationが失敗する場合、原因はmcp-graphql側ではなくAPI側の認可設定であることがほとんどです。HEADERSで渡しているトークンにMutation実行の権限が付与されているかを、GraphQL API側のドキュメントで確認します。

まとめ

mcp-graphqlは、GraphQL APIをMCP経由でClaudeに繋ぐための最小構成の実装です。ENDPOINTだけ指定すればすぐに動き始め、HEADERSで認証を、ALLOW_MUTATIONSで書き込み権限を、SCHEMAでIntrospection依存を、それぞれ必要になった時点で足していけます。既定でMutationが無効という設計は、そのまま安全な導入手順にもなっています。まず読み取り専用で繋ぎ、書き込みが必要になった段階で本番・検証の分離を検討する、という順序が妥当です。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →