graphql-to-mcp

graphql-to-mcp

Convierte cualquier API GraphQL en herramientas MCP — cero configuración, cero código.

Apunta graphql-to-mcp a un endpoint GraphQL y genera automáticamente una herramienta MCP por cada consulta/mutación mediante introspección. Funciona con Claude Desktop, Cursor, Windsurf y cualquier cliente MCP.

Inicio Rápido

Pruébalo ahora — sin necesidad de instalación:

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

O agrégalo a la configuración de Claude Desktop / Cursor:

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

Eso es todo. Claude ahora puede consultar países, continentes e idiomas.

Características

• Cero configuración — solo proporciona una URL de endpoint GraphQL
• Auto-introspección — descubre todas las consultas y mutaciones automáticamente
• Esquemas de parámetros planos — los objetos anidados de input se aplanan para una mejor precisión del LLM
• Truncamiento inteligente — las respuestas grandes se podan de forma inteligente (división de arrays + limitación de profundidad)
• Soporte de autenticación — tokens Bearer, claves API (encabezado o consulta)
• Lógica de reintentos — reintentos automáticos en 429/5xx con retroceso exponencial
• Filtros de inclusión/exclusión — expón solo las operaciones que desees
• Caché de esquema — omite la re-introspección con --schema-cache para un inicio más rápido
• Seguridad de mutaciones — detecta automáticamente mutaciones destructivas (delete*, remove*, etc.) y advierte o bloquea

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

Configuración de 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"],
});

Cómo Funciona

1. Introspección — Obtiene el esquema GraphQL mediante consulta de introspección
2. Aplanar — Los tipos anidados de InputObject se aplanan en parámetros simples de clave-valor (por ejemplo, input.name → input_name)
3. Generar — Cada consulta/mutación se convierte en una herramienta MCP con un JSON Schema plano
4. Ejecutar — Cuando un LLM llama a una herramienta, los argumentos planos se reconstruyen en variables GraphQL adecuadas y se envían a tu endpoint

¿Por Qué Esquemas Planos?

Los LLM son significativamente mejores completando parámetros planos de clave-valor que objetos JSON profundamente anidados. Al aplanar los tipos de InputObject, obtenemos:

• Mayor precisión al completar parámetros
• Menos estructuras anidadas alucinadas
• Mejor compatibilidad entre diferentes proveedores de LLM

Opciones

Opción	Descripción	Predeterminado
--bearer <token>	Autenticación con token Bearer	—
--api-key <name:value:in>	Autenticación con clave API	—
-H, --header <name:value>	Encabezado personalizado (repetible)	—
--include <pattern>	Incluir solo operaciones coincidentes	todas
--exclude <pattern>	Excluir operaciones coincidentes	ninguna
--prefix <name>	Prefijo del nombre de la herramienta	—
--timeout <ms>	Tiempo de espera de solicitud	30000
--max-retries <n>	Reintentar en 429/5xx	3
--transport <stdio|sse>	Transporte MCP	stdio
--schema-cache <path>	Guardar/cargar caché de introspección	—
--force-refresh	Ignorar caché, re-introspeccionar	false
--mutation-safety <mode>	warn | safe | unrestricted	warn

Truncamiento Inteligente

Las APIs GraphQL pueden devolver cargas útiles grandes que abruman las ventanas de contexto del LLM. graphql-to-mcp automáticamente:

• Divide arrays en 20 elementos (con metadatos que muestran el recuento total)
• Poda la profundidad más allá de 5 niveles (con resúmenes de objetos/arrays)
• Trunca de forma estricta a 50K caracteres como red de seguridad

Caché de Esquema

Las consultas de introspección pueden ser lentas en esquemas grandes. Usa --schema-cache para guardar el resultado de la introspección 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

El archivo de caché almacena la URL del endpoint y la marca de tiempo. Si apuntas a un endpoint diferente, automáticamente re-introspecciona.

Seguridad de Mutaciones

Por defecto, graphql-to-mcp detecta mutaciones destructivas y agrega advertencias a sus descripciones. Esto ayuda a los LLM a comprender el riesgo antes de ejecutarlas.

Patrones detectados: delete*, remove*, drop*, clear*, truncate*, destroy*, purge*, reset* (sin distinción de mayúsculas/minúsculas).

Modo	Comportamiento
warn (predeterminado)	Agrega el prefijo "DESTRUCTIVE:" a las descripciones de mutaciones peligrosas
safe	Excluye completamente las mutaciones peligrosas de la lista de herramientas
unrestricted	Sin filtrado ni advertencias (comportamiento 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

Úsalo También con APIs REST

Combínalo con mcp-openapi para darle a Claude acceso tanto a APIs REST como 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 — El mismo enfoque de cero configuración para APIs REST/OpenAPI

Licencia

MIT