home / mcp / graphql mcp server

Graphql MCP Server

An model context protocol adapted to running and list graphql queries

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "fabrwill-gql-mcp": {
      "command": "npx",
      "args": [
        "mcp-graphql"
      ],
      "env": {
        "HEADERS": "{\"x-api-key\":\"apikey\"}",
        "ENDPOINT": "https://localhost",
        "ALLOW_MUTATIONS": "false"
      }
    }
  }
}

You can run a GraphQL-based model context MCP server that lets you execute GraphQL queries against a remote endpoint with configurable headers and mutation control. This server exposes a lightweight bridge for your MCP client to introspect the schema and run queries within your authorized context.

How to use

To use this MCP server, point your MCP client at the server’s GraphQL endpoint and supply any required headers. You can enable or disable mutation operations to control how your client can modify data. Start by configuring the environment variables to match your target endpoint and authentication scheme, then run the server as an MCP connection. Once running, you can introspect the schema and execute queries through the standard MCP workflow.

How to install

Prerequisites: you need Node.js and npm installed on your machine.

# Install dependencies
npm i

# Build the package
npm run build

Use the following MCP configuration to run the GraphQL MCP server locally via npx. This creates a stdio-based MCP endpoint named gql-mcp-server that executes the mcp-graphql package. The configuration includes the required environment variables ENDPOINT and HEADERS.

{
  "mcpServers": {
    "gql-mcp-server": {
      "command": "npx",
      "args": ["mcp-graphql"],
      "env": {
          "ENDPOINT": "https://localhost",
          "HEADERS": "{\"x-api-key\":\"apikey\"}"
      }
    }
  }
}

You can verify the setup by running the MPC inspector against the local build to inspect the server state.

npx -y @modelcontextprotocol/inspector node dist/index.js inspect

Additional configuration notes

Environment variables you can use with this server are:

- ENDPOINT: GraphQL endpoint URL. Defaults to http://localhost:4000/graphql.

- HEADERS: JSON string containing headers for requests. Defaults to {}.

- ALLOW_MUTATIONS: Enable mutation operations (set to true to allow). Defaults to false.

Notes on testing and tooling

The server supports two primary tools for working with GraphQL in this MCP setup: one to introspect the schema and another to execute GraphQL queries.

Available tools

introspect

Retrieves the GraphQL schema from the endpoint to index or discover available operations.

query

Executes GraphQL queries against the configured endpoint to fetch data or test queries.