home / mcp / graphql mcp server

GraphQL MCP Server

MCP server for dynamic graphql

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ctkadvisors-graphql-mcp": {
      "command": "node",
      "args": [
        "dist/graphql-mcp-server.js"
      ],
      "env": {
        "GRAPHQL_API_KEY": "your-api-key-if-needed",
        "ENABLE_MUTATIONS": "true",
        "WHITELISTED_QUERIES": "[\"countries\",\"continent\",\"languages\"]",
        "GRAPHQL_API_ENDPOINT": "https://your-graphql-api.com/graphql"
      }
    }
  }
}

You can connect any GraphQL API to Claude as an MCP server. This setup automatically discovers GraphQL operations, exposes them as tools, and supports both queries and mutations with optional whitelisting for security and performance.

How to use

You run the MCP server locally and connect it to Claude Desktop. Once connected, GraphQL operations from the configured endpoint appear as tools you can invoke. You can query data by selecting a specific operation and optionally provide variables. For mutations, ensure they are enabled if you need to modify data, and you can restrict which mutations are exposed using whitelists.

How to install

Prerequisites: Node.js 18 or later, npm, TypeScript tooling if you build from source, and Claude Desktop with MCP support.

Option 1 — Install globally and run the server directly.

# Install globally
npm install -g graphql-mcp

# Run the server
graphql-mcp-server

Option 2 — Clone the project, install dependencies, build, and run.

git clone https://github.com/ctkadvisors/graphql-mcp.git
cd graphql-mcp
npm install
npm run build
node dist/graphql-mcp-server.js

If you prefer an all-in-one script, you can use the provided runner to compile and start in one step (when available in your environment).

./run-graphql-mcp.sh

Additional setup and integration

Prepare environment variables for Claude Desktop configuration. At minimum, point to your GraphQL endpoint and enable any desired features such as mutations and whitelisting.

The typical configuration includes an endpoint and optional API key, plus whitelisted queries and mutations to restrict exposure.

Notes on usage with Claude Desktop

Add the MCP server to Claude Desktop and point it to the runtime command you use (for example, node dist/graphql-mcp-server.js) along with environment variables that configure the GraphQL endpoint and access controls.

Security and best practices

Only enable mutations if you need data modification. Use whitelists to constrain exposed operations and reduce surface area. Keep API keys and sensitive values in environment variables and avoid hard-coding them in commands or source files.

Examples of common workflows

Query a list of countries, continents, or languages from the connected GraphQL API and pass parameters as needed to filter results.

Perform mutations only after enabling mutations and adding explicit whitelists, then invoke the mutation tool with the required input object.