mcp-graphql

mcp-graphql exposes a GraphQL-focused MCP server that lets language models discover and query GraphQL APIs. It supports automatic schema introspection and execution of GraphQL queries against a configured endpoint. Two core tools are available: introspect-schema, which retrieves and exposes the GraphQL schema (whether from a local schema file, a hosted schema, or via introspection), and query-graphql, which runs GraphQL queries against the endpoint. Mutations are disabled by default for safety, and can be enabled by setting ALLOW_MUTATIONS to true. To use the server, point it at your GraphQL endpoint via the ENDPOINT env var, optionally provide headers with HEADERS, and (if you have a local schema) specify SCHEMA. The NAME env var simply identifiers the MCP server in logs and UI.

Prerequisites:

• Node.js and npm installed on your machine
• npx available (comes with npm)

1. Install via Smithery (automatic installation for Claude Desktop):

# Install mcp-graphql client for Claude via Smithery
npx -y @smithery/cli install mcp-graphql --client claude

2. Manual installation (no Smithery):

1. Ensure Node.js and npm are installed.
2. Install and run the MCP server via npx (as shown in the README):

# Basic run using npx
ENDPOINT=http://localhost:4000/graphql npx mcp-graphql

3. If you want to configure via a manifest file (recommended for integration):

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

Notes:

• The server expects environment-based configuration (ENDPOINT, HEADERS, ALLOW_MUTATIONS, SCHEMA, NAME).
• By default mutations are disabled for safety.
• You can provide a local or remote GraphQL schema via SCHEMA; if omitted, the server will introspect the endpoint.

Tips and considerations:

• Ensure your GraphQL endpoint is reachable from the host running the MCP server.
• If your GraphQL API requires authentication, populate HEADERS with a valid JSON string, e.g. {"Authorization": "Bearer token"}.
• If you need to enable mutations, set ALLOW_MUTATIONS=true, but be aware of potential security implications.
• If you have a static schema file, set SCHEMA to its path or URL for faster startup and consistent introspection results.
• The NAME env var helps identify the MCP server instance in logs and dashboards.
• When using npx, the first run may download the package; subsequent runs will reuse the local cache.