mcp-graphql is a Model Context Protocol (MCP) server used to enable large language models (LLMs) to interact with GraphQL APIs. This implementation provides schema introspection and query execution capabilities, allowing models to dynamically discover and use GraphQL APIs.
Purpose and Positioning This project acts as a bridge between LLMs and GraphQL services: after running mcp-graphql with the correct endpoint, it automatically attempts to introspect the query, enabling the model to understand the available GraphQL schema and execute queries.
Main Capabilities
- Schema introspection: exposes the GraphQL schema as a client-accessible resource, which can originate from a local schema file, a schema file hosted at a URL, or be generated based on an introspection query.
- Query execution: provides the query-graphql tool to execute GraphQL queries against the configured endpoint.
- Two main tools: introspect-schema is used to obtain the GraphQL schema (use this first when the schema is not accessed as a resource); query-graphql is used to execute GraphQL queries.
Usage
- Environment variables: since version 1.0.0, command-line arguments have been replaced by environment variables, which is a breaking change. graphql-schema is used to specify the schema source (local file, remote URL, or introspection query).
- Installation: GraphQL MCP Server can be automatically installed for Claude Desktop via Smithery; it can also be manually installed into Claude.
- Secure defaults: mutations are disabled by default unless ALLOW_MUTATIONS is set to true.
Applicable Scenarios
- Enable LLMs to dynamically discover and use GraphQL APIs.
- When needed, first introspect the schema, then execute read-only queries against the endpoint.
Limitations and Security Considerations
- Mutations are disabled by default as a security measure to prevent LLMs from modifying databases or service data; carefully consider before enabling mutations in a production environment.
- This implementation is very general and allows full introspection and arbitrary operations by the user, including mutations; if a more specific implementation is needed, it is recommended tocreate your own MCP and lock the client's tool calls to only allow input of specific query fields and/or variables, using this project as a reference.
