📌Overview

Purpose: The mcp-graphql framework aims to facilitate communication between Large Language Models (LLMs) and GraphQL APIs through dynamic schema introspection and query execution.

Overview: mcp-graphql is a Model Context Protocol server tailored for integrating LLMs with GraphQL APIs. It enables models to automatically discover the schema of GraphQL endpoints and execute queries, providing an adaptable interface for developers and users alike.

Key Features:

• Introspect Schema: Retrieves the GraphQL schema either from a local file or via introspection, allowing for dynamic understanding of available queries and types.

• Execute Queries: Supports execution of GraphQL queries against an endpoint, with optional activation of mutation operations for interaction with data.

---

mcp-graphql

A 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.

Usage

Run mcp-graphql with the correct endpoint, it will automatically try to introspect your queries.

Environment Variables (Breaking change in 1.0.0)

Note: As of version 1.0.0, command line arguments have been replaced with environment variables.

Environment Variable	Description	Default
ENDPOINT	GraphQL endpoint URL	http://localhost:4000/graphql
HEADERS	JSON string containing request headers	{}
ALLOW_MUTATIONS	Enable mutation operations (disabled by default)	false
NAME	Name of the MCP server	mcp-graphql
SCHEMA	Path to a local GraphQL schema file (optional)	-

Examples

# Basic usage with a local GraphQL server
ENDPOINT=http://localhost:3000/graphql npx mcp-graphql

# Using with custom headers
ENDPOINT=https://api.example.com/graphql HEADERS='{"Authorization":"Bearer token123"}' npx mcp-graphql

# Enable mutation operations
ENDPOINT=http://localhost:3000/graphql ALLOW_MUTATIONS=true npx mcp-graphql

# Using a local schema file instead of introspection
ENDPOINT=http://localhost:3000/graphql SCHEMA=./schema.graphql npx mcp-graphql

Resources

• graphql-schema: The server exposes the GraphQL schema as a resource that clients can access, either from the local schema file or based on an introspection query.

Available Tools

The server provides two main tools:

1. introspect-schema: Retrieves the GraphQL schema. Use this first if you don't have access to the schema as a resource. It uses either a local schema file or an introspection query.

2. query-graphql: Executes GraphQL queries against the endpoint. Mutations are disabled by default unless ALLOW_MUTATIONS is set to true.

Installation

Installing via Smithery

To install GraphQL MCP Server for Claude Desktop automatically via Smithery:

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

Installing Manually

It can be manually installed to Claude:

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

Security Considerations

Mutations are disabled by default as a security measure to prevent unauthorized modifications to your database or service data. Consider carefully before enabling mutations in production environments.

Customize for your own server

This is a very generic implementation allowing complete introspection and user operations including mutations. For more specific implementations, create your own MCP and restrict tool calling to allow only specific query fields and/or variables. You can use this as a reference.