GraphQL MCP サーバー

Claude AI を通じてあらゆる GraphQL API へのシームレスなアクセスを提供する、厳密に型指定された TypeScript モデルコンテキストプロトコル (MCP) サーバー。

特徴

強く型付けされた: TypeScript で構築され、コードの品質と型の安全性が向上しています
動的GraphQL統合：自動ツール生成で任意のGraphQL APIに接続
スキーマイントロスペクション: すべてのGraphQL操作をツールとして自動的に検出して公開します
完全なミューテーションサポート: GraphQLミューテーションを適切に処理するファーストクラスのサポート
クエリとミューテーションのホワイトリスト: GraphQL 操作の公開を制御するためのオプションのホワイトリスト
豊富な型のサポート:複雑なGraphQL型、入力オブジェクト、変数を適切に処理します
MCP標準準拠:シームレスなClaude統合を実現するモデルコンテキストプロトコル形式に準拠
スマートクエリ生成:適切なフィールド選択による効率的なGraphQLクエリを構築します。
認証サポート: シンプルなAPIキー認証

リポジトリ構造

graphql-mcp/
├── src/
│   └── graphql-mcp-server.ts     # Main server implementation (TypeScript)
├── dist/                         # Compiled JavaScript (generated)
├── docs/
│   ├── GETTING_STARTED.md         # Setup and usage guide
│   ├── PROJECT_STATUS.md          # Current project status
│   └── TECHNICAL.md               # Technical documentation
├── .env.development               # Environment variables
├── .env.sample                    # Sample environment template
├── claude_desktop_sample_config.json  # Sample Claude Desktop config
├── package.json                   # Project dependencies
├── tsconfig.json                  # TypeScript configuration
├── run-graphql-mcp.sh             # Script to run the server
└── README.md                      # This file

前提条件

Node.js 18以降
TypeScript 5.x 以降
MCPサポート付きClaudeデスクトップ
GraphQL API エンドポイント (指定されていない場合はデフォルトで Countries API になります)

インストール

オプション1: npmから

# Install globally
npm install -g graphql-mcp

# Run the server
graphql-mcp-server

オプション2: リポジトリのクローン

# Clone the repository
git clone https://github.com/ctkadvisors/graphql-mcp.git
cd graphql-mcp

# Install dependencies
npm install

# Run the server
npm start

クイックスタート

1. 環境変数を設定する

サンプル env ファイルをコピーし、GraphQL API の詳細で更新します。

cp .env.sample .env.development

GraphQL API エンドポイントとオプションの API キーを使用して.env.developmentを編集します。

2. ビルドと実行

まず TypeScript コードをコンパイルします。

npm install
npm run build

次にサーバーを実行します。

node dist/graphql-mcp-server.js

または、1 ステップでコンパイルして実行する提供されたスクリプトを使用します。

./run-graphql-mcp.sh

3. クロードデスクトップ統合

このサーバーを Claude Desktop 構成に追加します。

サンプル設定をテンプレートとして使用します。
cp claude_desktop_sample_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
設定を編集し、インストールを指すようにパスを更新します。
{ "mcpServers": { "graphql": { "command": "node", "args": ["/absolute/path/to/dist/graphql-mcp-server.js"], "env": { "GRAPHQL_API_ENDPOINT": "https://your-graphql-api.com/graphql", "GRAPHQL_API_KEY": "your-api-key-if-needed", "WHITELISTED_QUERIES": "[\"countries\",\"continent\",\"languages\"]" } } } }
サーバーに接続するには、Claude Desktopを再起動してください。

これで、Claude Desktop で GraphQL 操作が利用可能なツールとして表示されるようになります。

ホワイトリスト作戦

セキュリティやパフォーマンス上の理由から、Claude に公開する GraphQL 操作（クエリとミューテーション）を制限したい場合があります。アクセス制御には 2 つの方法があります。

ミューテーションの有効化/無効化: セキュリティ上の理由により、デフォルトではすべてのミューテーションが無効になっています。ミューテーションを有効にするには、以下の手順を実行してください。

"env": {
  "GRAPHQL_API_ENDPOINT": "https://example-graphql-api.com/graphql",
  "ENABLE_MUTATIONS": "true"
}

操作のホワイトリスト: 利用できる特定の操作を指定できます。

"env": {
  "GRAPHQL_API_ENDPOINT": "https://example-graphql-api.com/graphql",
  "ENABLE_MUTATIONS": "true",
  "WHITELISTED_QUERIES": "[\"countries\",\"continent\",\"languages\"]",
  "WHITELISTED_MUTATIONS": "[\"createUser\",\"updateProfile\"]"
}

ホワイトリストは次の 2 つの形式で指定できます。

JSON 配列文字列として (上記参照): "[\"query1\",\"query2\"]"
カンマ区切りのリスト: "query1,query2,query3"

重要：ホワイトリストの値は、実際のJSON配列オブジェクトではなく、文字列である必要があります。環境変数は常に文字列として渡されるため、上記のようにJSON文字列内の引用符を適切にエスケープする必要があります。

Claude Desktop 構成における正しい形式の例:

"graphql-api": {
  "command": "node",
  "args": [
    "/Users/username/Projects/graphql-mcp/dist/graphql-mcp-server.js"
  ],
  "env": {
    "GRAPHQL_API_ENDPOINT": "https://example-graphql-api.com/graphql",
    "NODE_ENV": "development",
    "DEBUG": "true",
    "ENABLE_MUTATIONS": "true",
    "WHITELISTED_QUERIES": "[\"getUser\",\"getProducts\",\"getOrders\"]",
    "WHITELISTED_MUTATIONS": "[\"createOrder\",\"updateProfile\"]"
  }
}

避けるべきよくある間違い:

// INCORRECT - Will not work!
"WHITELISTED_QUERIES": ["getUser", "getProducts"],
"WHITELISTED_MUTATIONS": ["createOrder", "updateProfile"]

// CORRECT
"WHITELISTED_QUERIES": "[\"getUser\",\"getProducts\"]",
"WHITELISTED_MUTATIONS": "[\"createOrder\",\"updateProfile\"]"

特定の操作タイプに対してホワイトリストが提供されていない場合は、GraphQL スキーマからのそのタイプのすべての操作が利用可能になります。

使用例

データのクエリ

Claude Desktop に接続すると、次のようなコマンドを使用できます。

View result from countries from graphql (local){}

またはパラメータ付き:

View result from country from graphql (local){
  "code": "US"
}

ミューテーションの使用

ミューテーションの場合、クエリと区別するためにツールにmutation_接頭辞が付きます。

View result from mutation_createUser from graphql (local){
  "name": "John Doe",
  "email": "john.doe@example.com"
}

あるいは、より複雑な突然変異:

View result from mutation_updateProduct from graphql (local){
  "id": "prod-123",
  "input": {
    "name": "Updated Product Name",
    "price": 29.99,
    "description": "This is an updated product description"
  }
}

ミューテーションはクエリと同じパターンに従いますが、GraphQL API でデータを変更できます。

ドキュメント

詳細については、以下を参照してください。

発達

サーバーに変更を加えるには:

src/graphql-mcp-server.tsの TypeScript ソースを修正します。
TypeScriptコードをコンパイルします: npm run build
コンパイルされたサーバーを実行します: node dist/graphql-mcp-server.js

npmへの公開

このパッケージを npm に公開するには:

# Make sure you're logged in to npm
npm login

# Build the project
npm run build

# Publish to npm
npm publish

パッケージには、 distディレクトリに事前にビルドされた JavaScript ファイルが含まれるため、追加のビルド手順なしですぐに使用できます。

ライセンス

このプロジェクトは、Business Source License 1.1 (BSL 1.1) に基づいてライセンスされており、次のことが許可されています。

非商用利用：このソフトウェアは非商用目的であれば使用できます。
社内業務使用: このソフトウェアは、ホストまたは管理サービスとして第三者に提供しない社内業務に使用できます。
オープンソース化: 2029年3月14日に、コードは自動的にMITライセンスに変換されます。

本ソフトウェアを商用利用（他者へのサービス提供を含む）するには、CTK Advisors からの商用ライセンスが必要です。詳細については、お問い合わせいただくか、ライセンスファイルをご覧ください。

BSL ライセンスは、オープンソースの可用性と持続可能な商用開発のバランスをとるように設計されており、非商用目的で誰もが無料でアクセスできるようにしながら、ソフトウェアを長期的にサポートおよび強化する能力を保護します。

GraphQL MCP Server

Integrations