home / mcp / mcp graphql server
Model Context Protocol server for GraphQL
Configuration
View docs{
"mcpServers": {
"blurrah-mcp-graphql": {
"url": "http://localhost:3000/graphql",
"headers": {
"NAME": "mcp-graphql",
"HEADERS": "{}",
"ENDPOINT": "http://localhost:3000/graphql",
"ALLOW_MUTATIONS": "false"
}
}
}
}You build an MCP GraphQL Server that lets large language models discover and execute GraphQL queries against a remote endpoint. It exposes the GraphQL schema so models can introspect available fields and run queries or mutations (when enabled), enabling dynamic, schema-aware interactions with GraphQL APIs.
To use this MCP server with an MCP client, you run the MCP server locally and point your client at the GraphQL endpoint. The server automatically introspects the GraphQL schema and exposes tools to fetch the schema and run queries against the endpoint. By default mutations are disabled for safety, but you can enable them if you trust the model and environment.
Typical workflows include: letting the model discover available GraphQL types and fields via schema introspection, then constructing and submitting queries to retrieve data or trigger mutations when enabled. You should provide the GraphQL endpoint you want to connect to, optional headers for authentication, and an optional local schema file or a remote schema URL if you are not using live introspection.
Prerequisites: you need a runtime capable of running Node.js and npm (or an environment that can run npx). Ensure you have at least Node.js 12+ installed on your system.
Step 1: Install and run the MCP server using the standard MCP runner with the endpoint you want to connect to. You can start with a local GraphQL server as the endpoint.
Step 2: Run the MCP server with the required environment variables. The key variables are ENDPOINT for the GraphQL URL, HEADERS for any authentication headers, and ALLOW_MUTATIONS to enable mutations when needed.
Step 3: If you want to customize the schema source, you can provide SCHEMA with a local file path or a URL to a schema. When SCHEMA is provided, the server will use that instead of performing an introspection query.
Example setup using a local GraphQL server with a basic configuration:
ENDPOINT=http://localhost:3000/graphql
npx mcp-graphql
```
Example with custom headers and mutation support (set ALLOW_MUTATIONS to true):
```
ENDPOINT=http://localhost:3000/graphql
HEADERS='{"Authorization":"Bearer token123"}'
ALLOW_MUTATIONS=true
npx mcp-graphql
```
Example using a local schema file instead of introspection:
```
ENDPOINT=http://localhost:3000/graphql
SCHEMA=./schema.graphql
npx mcp-graphql
```
Example using a schema file hosted at a URL:
```
ENDPOINT=http://localhost:3000/graphql
SCHEMA=https://example.com/schema.graphql
npx mcp-graphql
`Mutations are disabled by default to reduce the risk of unintended data changes. Enable mutations only when you understand the security implications and you are running in a trusted environment.
The server offers schema access as a resource that can be the local file, a URL to a schema file, or based on an introspection query. Provide a local SCHEMA file or a remote URL to avoid relying on live introspection if you already have a schema handy.
If you run into connection issues, verify that ENDPOINT is reachable from the environment where you start the MCP server. Check any provided HEADERS for correct authentication values and ensure the endpoint allows the operations you intend to perform.
If mutations are failing after enabling ALLOW_MUTATIONS, confirm that the GraphQL endpoint supports mutations and that you have the necessary permissions. Review any server-side access controls or rate limits that might interfere with mutation execution.
Retrieves the GraphQL schema via local, remote, or introspection-based sources to expose the available types and fields.
Executes GraphQL queries against the configured endpoint, with mutations disabled by default unless explicitly enabled.