mikhailgarber/stateful-graphql-mcp

GraphQL MCP Server

A Model Context Protocol (MCP) server that provides tools to interact with GraphQL endpoints. This server allows Claude Desktop to introspect GraphQL schemas and execute queries/mutations against any GraphQL API.

Features

• GraphQL Introspection: Discover available types, queries, and mutations in a GraphQL schema
• Query/Mutation Execution: Execute GraphQL queries and mutations with variables support
• Environment-based Configuration: Configure GraphQL endpoint and headers via environment variables
• Claude Desktop Integration: Ready to use with Claude Desktop

Tools Provided

1. graphql_introspect

Introspects the GraphQL schema to discover available types, queries, and mutations.

Parameters: None

Returns: The GraphQL schema in SDL format plus raw introspection data

2. graphql_execute

Executes GraphQL queries and mutations against the configured endpoint.

Parameters:

• query (required): The GraphQL query or mutation to execute
• variables (optional): Variables to pass to the GraphQL query/mutation

Returns: The JSON response from the GraphQL endpoint

Setup

1. Install dependencies:

npm install

2. Build the project:

npm run build

3. Create a .env file with your GraphQL configuration:

cp .env.example .env

4. Edit .env with your GraphQL endpoint and headers:

GRAPHQL_ENDPOINT=https://your-graphql-api.com/graphql
GRAPHQL_HEADERS={"Authorization": "Bearer your-token", "Content-Type": "application/json"}

Claude Desktop Configuration

Add this server to your Claude Desktop configuration file:

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Windows

%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "graphql": {
      "command": "node",
      "args": ["/path/to/your/project/dist/index.js"],
      "env": {
        "GRAPHQL_ENDPOINT": "https://your-graphql-api.com/graphql",
        "GRAPHQL_HEADERS": "{\"Authorization\": \"Bearer your-token\", \"Content-Type\": \"application/json\"}"
      }
    }
  }
}

Development

Run in development mode:

npm run dev

Environment Variables

• GRAPHQL_ENDPOINT: The URL of your GraphQL endpoint (required)
• GRAPHQL_HEADERS: JSON string containing headers to send with requests (optional)

Example Usage

Once configured with Claude Desktop, you can:

1. Introspect a schema:

   • Ask Claude: "Can you introspect the GraphQL schema to see what's available?"

2. Execute queries:

   • Ask Claude: "Can you run a query to get all users?"
   • Claude will use the graphql_execute tool with an appropriate query

3. Execute mutations:

   • Ask Claude: "Can you create a new user with name 'John' and email 'john@example.com'?"
   • Claude will construct and execute the appropriate mutation

License

MIT