mcp-graphql

mcp-graphql

LLM が GraphQL API とやり取りできるようにする Model Context Protocol サーバーです。この実装では、スキーマのイントロスペクションとクエリの実行機能を提供し、モデルが GraphQL API を動的に検出して利用できるようにします。

使用方法

適切なエンドポイントを指定して mcp-graphql を実行すると、クエリのイントロスペクションが自動的に試みられます。

環境変数（1.0.0 での破壊的変更）

注： バージョン 1.0.0 以降、コマンドライン引数は環境変数に置き換えられています。

環境変数	説明	デフォルト
ENDPOINT	GraphQL エンドポイントの URL	http://localhost:4000/graphql
HEADERS	リクエスト用ヘッダーを含む JSON 文字列	{}
ALLOW_MUTATIONS	ミューテーション操作を有効にします（デフォルトでは無効）	false
NAME	MCP サーバーの名前	mcp-graphql
SCHEMA	ローカル GraphQL スキーマファイルまたは URL のパス（任意）	-

例

# Basic usage with a local GraphQL server
ENDPOINT=http://localhost:3000/graphql npx mcp-graphql

# Using with custom headers
ENDPOINT=https://api.example.com/graphql HEADERS='{"Authorization":"Bearer token123"}' npx mcp-graphql

# Enable mutation operations
ENDPOINT=http://localhost:3000/graphql ALLOW_MUTATIONS=true npx mcp-graphql

# Using a local schema file instead of introspection
ENDPOINT=http://localhost:3000/graphql SCHEMA=./schema.graphql npx mcp-graphql

# Using a schema file hosted at a URL
ENDPOINT=http://localhost:3000/graphql SCHEMA=https://example.com/schema.graphql npx mcp-graphql

リソース

• graphql-schema：サーバーは、クライアントがアクセスできるリソースとして GraphQL スキーマを公開します。これは、ローカルのスキーマファイル、URL でホストされているスキーマファイル、またはイントロスペクションクエリに基づくスキーマのいずれかです。

利用可能なツール

サーバーは、主に 2 つのツールを提供します。

1. introspect-schema：このツールは GraphQL スキーマを取得します。スキーマにリソースとしてアクセスできない場合は、まずこれを使用してください。 ローカルのスキーマファイル、URL でホストされているスキーマファイル、またはイントロスペクションクエリのいずれかを使用します。

2. query-graphql：エンドポイントに対して GraphQL クエリを実行します。デフォルトでは、ALLOW_MUTATIONS が true に設定されていない限り、ミューテーションは無効です。

インストール

Smithery 経由でのインストール

Smithery 経由で Claude Desktop に GraphQL MCP Server を自動的にインストールするには：

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

手動でのインストール

Claude に手動でインストールできます：

{
    "mcpServers": {
        "mcp-graphql": {
            "command": "npx",
            "args": ["mcp-graphql"],
            "env": {
                "ENDPOINT": "http://localhost:3000/graphql"
            }
        }
    }
}

セキュリティに関する考慮事項

LLM がデータベースやサービスのデータを変更できないようにするセキュリティ対策として、ミューテーションはデフォルトで無効になっています。本番環境でミューテーションを有効にする前に、慎重に検討してください。

独自のサーバー向けにカスタマイズする

これは、完全なイントロスペクションを可能にし、ユーザーが何でも（ミューテーションを含めて）実行できる、非常に汎用的な実装です。より具体的な実装が必要な場合は、独自の MCP を作成し、クライアントが特定のクエリフィールドや変数のみを入力できるようにツール呼び出しを制限することをお勧めします。参考としてご利用ください。