mcp-graphql-interface

An enhanced Model Context Protocol (MCP) service engineered for seamless integration with GraphQL APIs. This module equips LLMs with the capacity to perform deep schema exploration and execute arbitrary GraphQL operations, ensuring dynamic access to backend data structures.

Operational Guidance

Execute mcp-graphql-interface pointing to your target endpoint. The system will self-configure by attempting schema reflection.

Configuration Parameters

Parameter	Purpose	Default Value
--endpoint	The URI of the GraphQL service	http://localhost:4000/graphql
--headers	A JSON string defining required HTTP request headers	{}
--enable-mutations	Toggles permission for write/update operations (off by default)	false
--name	Identifier for this specific MCP instance	mcp-graphql-interface
--schema	Path to a pre-existing local schema definition file (optional fallback)	N/A

Practical Scenarios

# Standard connection to a local instance
npx mcp-graphql-interface --endpoint http://localhost:3000/graphql

# Securing access using custom headers
npx mcp-graphql-interface --endpoint https://api.example.com/graphql --headers '{"Authorization":"Bearer token123"}'

# Activating data modification capabilities
npx mcp-graphql-interface --endpoint http://localhost:3000/graphql --enable-mutations

# Bypassing introspection using a local schema file
npx mcp-graphql-interface --endpoint http://localhost:3000/graphql --schema ./local_api_schema.gql

Provided Functionality

The server exposes two primary interaction tools:

1. retrieve-schema: Fetches the complete GraphQL schema definition. This is the prerequisite step if the schema structure is unknown, relying on either an introspection query or the provided local file.

2. execute-query: Handles the submission of GraphQL queries (and optional mutations, if enabled) to the target endpoint.

Data Resources

• schema-definition: The system makes the discovered or loaded GraphQL schema available as an accessible resource for client inspection.

Installation Procedures

Smithery Automated Deployment

To instantly integrate this GraphQL MCP Server with Claude Desktop via Smithery:

npx -y @smithery/cli install mcp-graphql-interface --client claude

Manual Configuration

Integrate manually into Claude's configuration file:

{
    "mcpServers": {
        "mcp-graphql-interface": {
            "command": "npx",
            "args": ["mcp-graphql-interface", "--endpoint", "http://localhost:3000/graphql"]
        }
    }
}

Safety Guidelines

Mutations are intentionally deactivated by default as a crucial security barrier, preventing unintended data modification by the executing agent. Thorough risk assessment is mandated before enabling write operations in production settings.

Customization Notes

This serves as a generalized framework supporting broad introspection and execution. For restricted environments, we advise creating a derivative MCP that strictly limits which query fields or input variables the model is permitted to construct. This implementation can serve as a foundational template.