MCP GraphQL

1# mcp-graphql
2 
3[![smithery badge](https://smithery.ai/badge/mcp-graphql)](https://smithery.ai/server/mcp-graphql)
4 
5A Model Context Protocol server that enables LLMs to interact with GraphQL APIs. This implementation provides schema introspection and query execution capabilities, allowing models to discover and use GraphQL APIs dynamically.
6 
7<a href="https://glama.ai/mcp/servers/4zwa4l8utf"><img width="380" height="200" src="https://glama.ai/mcp/servers/4zwa4l8utf/badge" alt="mcp-graphql MCP server" /></a>
8 
9## Usage
10 
11Run `mcp-graphql` with the correct endpoint, it will automatically try to introspect your queries.
12 
13### Environment Variables (Breaking change in 1.0.0)
14 
15> **Note:** As of version 1.0.0, command line arguments have been replaced with environment variables.
16 
17| Environment Variable | Description | Default |
18|----------|-------------|---------|
19| `ENDPOINT` | GraphQL endpoint URL | `http://localhost:4000/graphql` |
20| `HEADERS` | JSON string containing headers for requests | `{}` |
21| `ALLOW_MUTATIONS` | Enable mutation operations (disabled by default) | `false` |
22| `NAME` | Name of the MCP server | `mcp-graphql` |
23| `SCHEMA` | Path to a local GraphQL schema file or URL (optional) | - |
24 
25### Examples
26 
27```bash
28# Basic usage with a local GraphQL server
29ENDPOINT=http://localhost:3000/graphql npx mcp-graphql
30 
31# Using with custom headers
32ENDPOINT=https://api.example.com/graphql HEADERS='{"Authorization":"Bearer token123"}' npx mcp-graphql
33 
34# Enable mutation operations
35ENDPOINT=http://localhost:3000/graphql ALLOW_MUTATIONS=true npx mcp-graphql
36 
37# Using a local schema file instead of introspection
38ENDPOINT=http://localhost:3000/graphql SCHEMA=./schema.graphql npx mcp-graphql
39 
40# Using a schema file hosted at a URL
41ENDPOINT=http://localhost:3000/graphql SCHEMA=https://example.com/schema.graphql npx mcp-graphql
42```
43 
44## Resources
45 
46- **graphql-schema**: The server exposes the GraphQL schema as a resource that clients can access. This is either the local schema file, a schema file hosted at a URL, or based on an introspection query.
47 
48## Available Tools
49 
50The server provides two main tools:
51 
521. **introspect-schema**: This tool retrieves the GraphQL schema. Use this first if you don't have access to the schema as a resource.
53This uses either the local schema file, a schema file hosted at a URL, or an introspection query.
54 
552. **query-graphql**: Execute GraphQL queries against the endpoint. By default, mutations are disabled unless `ALLOW_MUTATIONS` is set to `true`.
56 
57## Installation
58 
59### Installing via Smithery
60 
61To install GraphQL MCP Server for Claude Desktop automatically via [Smithery](https://smithery.ai/server/mcp-graphql):
62 
63```bash
64npx -y @smithery/cli install mcp-graphql --client claude
65```
66 
67### Installing Manually
68 
69It can be manually installed to Claude:
70```json
71{
72    "mcpServers": {
73        "mcp-graphql": {
74            "command": "npx",
75            "args": ["mcp-graphql"],
76            "env": {
77                "ENDPOINT": "http://localhost:3000/graphql"
78            }
79        }
80    }
81}
82```
83 
84## Security Considerations
85 
86Mutations are disabled by default as a security measure to prevent an LLM from modifying your database or service data. Consider carefully before enabling mutations in production environments.
87 
88## Customize for your own server
89 
90This is a very generic implementation where it allows for complete introspection and for your users to do whatever (including mutations). If you need a more specific implementation I'd suggest to just create your own MCP and lock down tool calling for clients to only input specific query fields and/or variables. You can use this as a reference.
91