Graphql To Mcp

graphql-to-mcp

あらゆる GraphQL API を MCP ツールに変換できます。設定もコードも不要です。

graphql-to-mcp に GraphQL エンドポイントを指定すると、イントロスペクションを通じてクエリ／ミューテーションごとに MCP ツールを自動生成します。Claude Desktop、Cursor、Windsurf、およびあらゆる MCP クライアントで動作します。

クイックスタート

今すぐ試す — インストールは不要です。

npx graphql-to-mcp https://countries.trevorblades.com/graphql

または、Claude Desktop／Cursor の設定に追加します。

{
  "mcpServers": {
    "countries": {
      "command": "npx",
      "args": ["-y", "graphql-to-mcp", "https://countries.trevorblades.com/graphql"]
    }
  }
}

これで完了です。Claude が国、大陸、言語をクエリできるようになります。

特長

• 設定不要 — GraphQL エンドポイント URL を指定するだけです
• 自動イントロスペクション — すべてのクエリとミューテーションを自動的に検出します
• フラットなパラメータースキーマ — ネストされた input オブジェクトをフラット化し、LLM の精度を高めます
• スマートな切り詰め — 大きなレスポンスをインテリジェントに削減します（配列のスライス＋深さ制限）
• 認証に対応 — Bearer トークン、API キー（ヘッダーまたはクエリ）
• リトライロジック — 429／5xx の場合に指数バックオフで自動リトライします
• 包含／除外フィルター — 公開する操作だけを選択できます
• スキーマキャッシュ — --schema-cache を使って再イントロスペクションを省略し、起動を高速化します
• ミューテーションの安全性 — 破壊的なミューテーション（delete*、remove* など）を自動検出し、警告またはブロックします

使い方

CLI

# Public API (no auth)
npx graphql-to-mcp https://countries.trevorblades.com/graphql

# With bearer token
npx graphql-to-mcp https://api.github.com/graphql --bearer ghp_xxxxx

# With API key
npx graphql-to-mcp https://api.example.com/graphql --api-key "X-API-Key:your-key:header"

# Filter operations
npx graphql-to-mcp https://api.example.com/graphql --include "get*" --exclude "internal*"

# With prefix (avoid name collisions when using multiple APIs)
npx graphql-to-mcp https://api.example.com/graphql --prefix myapi

# Cache schema locally for faster restarts
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json

# Force re-introspection (ignore cache)
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json --force-refresh

# Block destructive mutations (delete*, remove*, etc.)
npx graphql-to-mcp https://api.example.com/graphql --mutation-safety safe

Claude Desktop／Cursor の設定

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": [
        "-y", "graphql-to-mcp",
        "https://api.github.com/graphql",
        "--bearer", "ghp_xxxxx",
        "--prefix", "github"
      ]
    }
  }
}

プログラムからの利用

import { createServer } from "graphql-to-mcp";

const server = await createServer({
  endpoint: "https://api.example.com/graphql",
  auth: { type: "bearer", token: "xxx" },
  include: ["getUser", "listUsers"],
});

動作の仕組み

1. イントロスペクト — イントロスペクションクエリを使って GraphQL スキーマを取得します
2. フラット化 — ネストされた InputObject 型を単純なキーと値のパラメーターにフラット化します（例：input.name → input_name）
3. 生成 — 各クエリ／ミューテーションを、フラットな JSON Schema を持つ MCP ツールに変換します
4. 実行 — LLM がツールを呼び出すと、フラットな引数を適切な GraphQL 変数に再構成し、エンドポイントに送信します

フラットなスキーマを使う理由

LLM は、深くネストされた JSON オブジェクトよりも、フラットなキーと値のパラメーターを大幅に正確に入力できます。InputObject 型をフラット化することで、次のメリットが得られます。

• パラメーター入力の精度向上
• 幻覚によるネスト構造の減少
• 各種 LLM プロバイダー間での互換性向上

オプション

オプション	説明	デフォルト
--bearer <token>	Bearer トークン認証	—
--api-key <name:value:in>	API キー認証	—
-H, --header <name:value>	カスタムヘッダー（繰り返し指定可能）	—
--include <pattern>	一致する操作のみを含めます	all
--exclude <pattern>	一致する操作を除外します	none
--prefix <name>	ツール名のプレフィックス	—
--timeout <ms>	リクエストのタイムアウト	30000
--max-retries <n>	429／5xx の場合にリトライします	3
--transport <stdio|sse>	MCP トランスポート	stdio
--schema-cache <path>	イントロスペクションキャッシュを保存／読み込みます	—
--force-refresh	キャッシュを無視して再イントロスペクトします	false
--mutation-safety <mode>	warn | safe | unrestricted	warn

スマートな切り詰め

GraphQL API は、LLM のコンテキストウィンドウを圧迫する大きなペイロードを返すことがあります。graphql-to-mcp は次の処理を自動で行います。

• 配列をスライスし、20 件に制限します（合計件数を示すメタデータ付き）
• 深さを削減し、5 レベルを超える部分を要約します（オブジェクト／配列の要約付き）
• 安全策として、50K 文字で強制的に切り詰めます

スキーマキャッシュ

大規模なスキーマでは、イントロスペクションクエリに時間がかかることがあります。--schema-cache を使うと、イントロスペクションの結果をローカルに保存できます。

# First run: introspects and saves to cache
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json

# Subsequent runs: loads from cache (instant startup)
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json

# Force re-introspection when the API schema changes
npx graphql-to-mcp https://api.example.com/graphql --schema-cache ./schema.json --force-refresh

キャッシュファイルには、エンドポイント URL とタイムスタンプが保存されます。別のエンドポイントを指定すると、自動的に再イントロスペクトします。

ミューテーションの安全性

デフォルトでは、graphql-to-mcp が破壊的なミューテーションを検出し、その説明に警告を追加します。これにより、LLM は実行前にリスクを把握できます。

検出されるパターン：delete*、remove*、drop*、clear*、truncate*、destroy*、purge*、reset*（大文字と小文字は区別されません）。

モード	動作
warn（デフォルト）	危険なミューテーションの説明に「DESTRUCTIVE:」という接頭辞を追加します
safe	危険なミューテーションをツール一覧から完全に除外します
unrestricted	フィルタリングも警告も行いません（以前の動作）

# Safe mode: only expose read queries + non-destructive mutations
npx graphql-to-mcp https://api.example.com/graphql --mutation-safety safe

# Unrestricted: expose everything (use with caution)
npx graphql-to-mcp https://api.example.com/graphql --mutation-safety unrestricted

REST API でも使用する

mcp-openapi と組み合わせると、Claude が REST API と GraphQL API の両方にアクセスできるようになります。

{
  "mcpServers": {
    "github-graphql": {
      "command": "npx",
      "args": ["-y", "graphql-to-mcp", "https://api.github.com/graphql", "--bearer", "ghp_xxx", "--prefix", "gh"]
    },
    "petstore-rest": {
      "command": "npx",
      "args": ["-y", "mcp-openapi", "https://petstore3.swagger.io/api/v3/openapi.json"]
    }
  }
}

関連項目

• mcp-openapi — REST/OpenAPI API 向けの同じゼロ設定アプローチ

ライセンス

MIT