mcp-graphql: MCP server for GraphQL APIs
mcp-graphql
Two GraphQL tools for MCP clients: the agent fetches your API schema and runs queries against a single endpoint
- 407 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The agent sends arbitrary queries to your API with the authorization headers from the config
- If ALLOW_MUTATIONS is enabled, the model can change and delete service data
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add mcp/mcp-graphqlDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The agent sends arbitrary queries to your API with the authorization headers from the config
- If ALLOW_MUTATIONS is enabled, the model can change and delete service data
This is third-party code. Review the repository files before installing.
What it does
mcp-graphql connects an agent to any GraphQL endpoint. The server gets the schema itself, through an introspection query, from a local file or from a URL, so the agent sees which types and fields the API has and writes queries to match. There are two tools. introspect-schema returns the schema, and query-graphql sends a query to the endpoint. MCP clients that read resources also receive the schema as a graphql-schema resource. The server is configured with environment variables: the endpoint address, request headers, a path to a schema file and the server name. Mutations are off by default so the model cannot change data in your service, and a separate variable turns them on.
Who it is for. For developers who debug or explore a GraphQL API together with an agent in Claude Desktop, Claude Code or Cursor.
Good fit when
- You need to find out which queries and types a third-party GraphQL API has without opening its docs
- An agent writes client code for your GraphQL backend and has to check fields against the schema
- You develop a GraphQL server locally on localhost and want to try queries straight from the conversation
- The schema is a file or a URL and introspection is unavailable on the server
- You are building an integration prototype where the agent reads API data on the fly
Not a fit when
- You need direct database access: the server talks only to a GraphQL endpoint
- You want to allow only a few preselected operations: here the model can send any query
- The API is REST or gRPC and has no GraphQL
- You need an integration for a production system with field restrictions, rate limits and query auditing
Example request
Connect to the GraphQL API on localhost:3000, show which queries the schema has and fetch the ten most recent orders.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
ENDPOINTrequired- GraphQL endpoint URL, defaults to http://localhost:4000/graphql
HEADERSsecret- JSON string with request headers, for example an auth token
ALLOW_MUTATIONS- The value true enables mutations; they are off by default
SCHEMA- Path or URL of a GraphQL schema file used instead of introspection
NAME- MCP server name, defaults to mcp-graphql
Limitations
The server is generic: it does not limit which fields and queries the model can reach. In the documentation example the token is passed as a string in the HEADERS variable, which puts the secret in the client's settings file.
The repository was last updated in September 2025. There is no interactive sign-in: access is set only by the headers in HEADERS, so a token for an API that uses browser login has to be obtained separately.
How to disable. Remove the mcp-graphql entry from the MCP client configuration and restart the client. If you installed it through Smithery, remove the server from that client's settings too. The server leaves no keys or background processes.
FAQ
How do I install mcp-graphql in Claude Desktop?
The author gives two ways. The first is the command npx -y @smithery/cli install mcp-graphql --client claude through Smithery. The second is a config entry with the command npx, the argument mcp-graphql and the ENDPOINT variable in the env block. The instructions name no other clients, but the launch is a regular stdio one.
How do I pass an auth token to the GraphQL API?
Through the HEADERS variable: a JSON string with request headers such as Authorization. The headers go out with every agent query, so give it a token with minimal rights.
Can I skip the introspection query?
Yes. The SCHEMA variable accepts a path to a local schema file or a URL to one. The introspect-schema tool then returns the schema from there instead of the endpoint.
Why did my old settings stop working after 1.0.0?
Since version 1.0.0 command line arguments have been replaced by environment variables. Move the address, headers and the rest into the env block.
What license does mcp-graphql use and what is it written in?
The project is released under the MIT license, with source code in TypeScript. The package is named mcp-graphql, and its launch command is mcp-graphql as well.
Discussion
No questions or reviews yet.
Related
MCP serversApollo's MCP server: turns chosen GraphQL operations into tools the agent uses to work with your API
A PostgreSQL MCP server with index tuning, EXPLAIN plans, database health checks and a read-only mode
A Laravel and Lumen package that adds an MCP endpoint to your app's routes and attaches your own tools to it
Instant REST and MCP over PostgreSQL: the agent reads an existing database through an MCP endpoint with no backend to write
Two official Prisma MCP servers: a local one for migrations and Prisma Studio, and a remote one for managing Prisma Postgres databases
Supabase's official MCP server: the agent manages tables, reads project config and queries data after an OAuth login
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| mcp-graphql: MCP server for GraphQL APIs (this entry) | no | not required | 407 | |
| Apollo MCP Server | yes | not required | 317 | turns predefined GraphQL operations into separate tools, which keeps the set of queries limited |
| GraphJin MCP | yes | not required | 3,225 | gives the agent access to SQL and MongoDB databases, while mcp-graphql works with a ready GraphQL endpoint |
README in short
The repository covers installation through Smithery and a manual config entry, then shows runs with a local server, custom headers, a schema file and a schema by URL. The author warns that the implementation is generic and advises building your own narrow MCP server for a production system, using this project as a reference.