graphql-to-mcp

graphql-to-mcp

Transforme qualquer API GraphQL em ferramentas MCP — zero configuração, zero código.

Aponte o graphql-to-mcp para um endpoint GraphQL e ele gera automaticamente uma ferramenta MCP por query/mutation via introspecção. Funciona com Claude Desktop, Cursor, Windsurf e qualquer cliente MCP.

Início Rápido

Experimente agora — sem necessidade de instalação:

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

Ou adicione à configuração do Claude Desktop / Cursor:

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

Pronto. O Claude agora pode consultar países, continentes e idiomas.

Recursos

• Zero configuração — basta fornecer a URL do endpoint GraphQL
• Introspecção automática — descobre todas as queries e mutations automaticamente
• Esquemas de parâmetros planos — objetos input aninhados são achatados para melhor precisão do LLM
• Truncamento inteligente — respostas grandes são podadas de forma inteligente (fatiamento de arrays + limite de profundidade)
• Suporte a autenticação — tokens Bearer, chaves de API (header ou query)
• Lógica de retry — novas tentativas automáticas em 429/5xx com backoff exponencial
• Filtros de inclusão/exclusão — exponha apenas as operações desejadas
• Cache de esquema — pule a reintrospecção com --schema-cache para inicialização mais rápida
• Segurança de mutations — detecta automaticamente mutations destrutivas (delete*, remove*, etc.) e avisa ou bloqueia

Uso

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

Configuração do Claude Desktop / Cursor

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

Programático

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

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

Como Funciona

1. Introspecção — Busca o esquema GraphQL via query de introspecção
2. Achatamento — Tipos InputObject aninhados são achatados em parâmetros simples de chave-valor (ex.: input.name → input_name)
3. Geração — Cada query/mutation vira uma ferramenta MCP com um JSON Schema plano
4. Execução — Quando um LLM chama uma ferramenta, os argumentos planos são reconstruídos em variáveis GraphQL adequadas e enviados ao seu endpoint

Por que Esquemas Planos?

LLMs são significativamente melhores em preencher parâmetros planos de chave-valor do que objetos JSON profundamente aninhados. Ao achatar tipos InputObject, obtemos:

• Maior precisão no preenchimento de parâmetros
• Menos estruturas aninhadas alucinadas
• Melhor compatibilidade entre diferentes provedores de LLM

Opções

Opção	Descrição	Padrão
--bearer <token>	Autenticação com token Bearer	—
--api-key <name:value:in>	Autenticação com chave de API	—
-H, --header <name:value>	Header personalizado (repetível)	—
--include <pattern>	Incluir apenas operações correspondentes	todas
--exclude <pattern>	Excluir operações correspondentes	nenhuma
--prefix <name>	Prefixo do nome da ferramenta	—
--timeout <ms>	Timeout da requisição	30000
--max-retries <n>	Retry em 429/5xx	3
--transport <stdio|sse>	Transporte MCP	stdio
--schema-cache <path>	Salvar/carregar cache de introspecção	—
--force-refresh	Ignorar cache, reintrospecção	false
--mutation-safety <mode>	warn | safe | unrestricted	warn

Truncamento Inteligente

APIs GraphQL podem retornar payloads grandes que sobrecarregam as janelas de contexto dos LLMs. O graphql-to-mcp automaticamente:

• Fatia arrays em 20 itens (com metadados mostrando o total)
• Poda a profundidade além de 5 níveis (com resumos de objetos/arrays)
• Trunca duramente em 50K caracteres como rede de segurança

Cache de Esquema

Queries de introspecção podem ser lentas em esquemas grandes. Use --schema-cache para salvar o resultado da introspecção localmente:

# 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

O arquivo de cache armazena a URL do endpoint e o timestamp. Se você apontar para um endpoint diferente, ele reintrospecção automaticamente.

Segurança de Mutations

Por padrão, o graphql-to-mcp detecta mutations destrutivas e adiciona avisos às suas descrições. Isso ajuda os LLMs a entenderem o risco antes de executá-las.

Padrões detectados: delete*, remove*, drop*, clear*, truncate*, destroy*, purge*, reset* (insensível a maiúsculas/minúsculas).

Modo	Comportamento
warn (padrão)	Adiciona o prefixo "DESTRUCTIVE:" às descrições de mutations perigosas
safe	Exclui completamente mutations perigosas da lista de ferramentas
unrestricted	Sem filtragem ou avisos (comportamento anterior)

# 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

Use com APIs REST Também

Combine com mcp-openapi para dar ao Claude acesso a APIs REST e GraphQL:

{
  "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"]
    }
  }
}

Relacionados

• mcp-openapi — A mesma abordagem de zero configuração para APIs REST/OpenAPI

Licença

MIT