Servidor GraphQL MCP

Un servidor de Protocolo de contexto de modelo (MCP) de TypeScript fuertemente tipado que proporciona acceso sin inconvenientes a cualquier API GraphQL a través de Claude AI.

Características

Fuertemente tipado : creado con TypeScript para mejorar la calidad del código y la seguridad de tipos.
Integración dinámica de GraphQL : conéctese a cualquier API de GraphQL con generación automática de herramientas
Introspección de esquema : descubre y expone automáticamente todas las operaciones GraphQL como herramientas
Soporte completo para mutaciones : soporte de primera clase para mutaciones GraphQL con manejo adecuado
Lista blanca de consultas y mutaciones : lista blanca opcional para controlar qué operaciones de GraphQL están expuestas
Compatibilidad con tipos enriquecidos : maneja adecuadamente tipos GraphQL complejos, objetos de entrada y variables
Compatible con el estándar MCP : sigue el formato del Protocolo de contexto de modelo para una integración perfecta con Claude
Generación de consultas inteligentes : crea consultas GraphQL eficientes con la selección de campos adecuada
Compatibilidad con autenticación : autenticación de clave API simple

Estructura del repositorio

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

Prerrequisitos

Node.js 18 o posterior
TypeScript 5.x o posterior
Claude Desktop con soporte para MCP
Un punto final de API GraphQL (el valor predeterminado es la API de países si no se especifica)

Instalación

Opción 1: Desde npm

# Install globally
npm install -g graphql-mcp

# Run the server
graphql-mcp-server

Opción 2: Clonar repositorio

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

# Install dependencies
npm install

# Run the server
npm start

Inicio rápido

1. Configurar variables de entorno

Copie el archivo env de muestra y actualícelo con los detalles de su API GraphQL:

cp .env.sample .env.development

Edite .env.development con su punto final de API GraphQL y su clave de API opcional.

2. Construir y ejecutar

Primero compila el código TypeScript:

npm install
npm run build

Luego ejecuta el servidor:

node dist/graphql-mcp-server.js

O utilice el script proporcionado que se compila y se ejecuta en un solo paso:

./run-graphql-mcp.sh

3. Integración de escritorio de Claude

Agregue este servidor a su configuración de Claude Desktop:

Utilice la configuración de muestra como plantilla:
cp claude_desktop_sample_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json
Edite la configuración y actualice la ruta para que apunte a su instalación:
{ "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\"]" } } } }
Reinicie Claude Desktop para conectarse al servidor

¡Ahora deberías ver las operaciones GraphQL como herramientas disponibles en Claude Desktop!

Operación Lista Blanca

Por razones de seguridad o rendimiento, puede que desee limitar las operaciones de GraphQL (consultas y mutaciones) expuestas a Claude. Existen dos enfoques para controlar el acceso:

Habilitar/Deshabilitar Mutaciones : Por seguridad, todas las mutaciones están deshabilitadas de forma predeterminada. Para habilitarlas:

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

Lista blanca de operaciones : puede especificar qué operaciones específicas deben estar disponibles:

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

Las listas blancas se pueden especificar en dos formatos:

Como una cadena de matriz JSON (mostrada arriba): "[\"query1\",\"query2\"]"
Como una lista separada por comas: "query1,query2,query3"

IMPORTANTE : Los valores de la lista blanca deben ser cadenas, no objetos de matriz JSON. Las variables de entorno siempre se pasan como cadenas, por lo que es necesario escapar correctamente las comillas en la cadena JSON, como se muestra arriba.

Ejemplo de formato correcto en la configuración de 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\"]"
  }
}

Error común a evitar :

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

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

Si no se proporciona una lista blanca para un tipo de operación en particular, todas las operaciones de ese tipo del esquema GraphQL estarán disponibles.

Ejemplo de uso

Consulta de datos

Una vez conectado a Claude Desktop, puedes usar comandos como:

View result from countries from graphql (local){}

O con parámetros:

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

Uso de mutaciones

Para las mutaciones, las herramientas tienen el prefijo mutation_ para distinguirlas de las consultas:

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

O una mutación más compleja:

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

Las mutaciones siguen el mismo patrón que las consultas, pero le permiten modificar datos en su API GraphQL.

Documentación

Para obtener información más detallada, consulte:

Desarrollo

Para realizar cambios en el servidor:

Modificar el código fuente de TypeScript en src/graphql-mcp-server.ts
Compilar el código TypeScript: npm run build
Ejecute el servidor compilado: node dist/graphql-mcp-server.js

Publicación en npm

Para publicar este paquete en npm:

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

# Build the project
npm run build

# Publish to npm
npm publish

El paquete incluirá los archivos JavaScript prediseñados en el directorio dist , lo que lo dejará listo para usar sin pasos de compilación adicionales.

Licencia

Este proyecto está licenciado bajo la Licencia Business Source 1.1 (BSL 1.1), que permite:

Uso no comercial : Puede utilizar este software para cualquier propósito no comercial.
Uso comercial interno : Puede utilizar este software para operaciones comerciales internas que no lo proporcionen a terceros como un servicio alojado o administrado.
Conversión de código abierto : el 14 de marzo de 2029, el código se convertirá automáticamente a la licencia MIT

El uso comercial, incluyendo la oferta de este software como servicio a terceros, requiere una licencia comercial de CTK Advisors. Para más información, contáctenos o consulte el archivo completo de la LICENCIA .

La licencia BSL está diseñada para equilibrar la disponibilidad de código abierto con el desarrollo comercial sustentable, brindando a todos acceso gratuito para fines no comerciales y al mismo tiempo protegiendo nuestra capacidad de respaldar y mejorar el software a largo plazo.

GraphQL MCP Server

Integrations