mcp4gql - GraphQL MCP Server

This project is a Node.js/TypeScript server that implements the Model Context Protocol (MCP). It acts as a bridge, allowing MCP clients (like Cursor) to interact with a target GraphQL API.

Features

• MCP Server: Implements the MCP `Server` class from `@modelcontextprotocol/sdk`.
• Stdio Transport: Communicates with clients via standard input/output.
• GraphQL Client: Uses `axios` to send requests to the configured GraphQL endpoint.
• Generic GraphQL Tools: Exposes the following tools to MCP clients:
  • `introspectGraphQLSchema`: Fetches the target GraphQL API schema using introspection.
  • `executeGraphQLOperation`: Executes arbitrary GraphQL queries or mutations against the target API, taking `query`, optional `variables`, and optional `operationName` as input.

Configuration

The server requires the following environment variables:

• `GRAPHQL_ENDPOINT`: The URL of the target GraphQL API.
• `AUTH_TOKEN`: A bearer token for an optional `Authorization: Bearer ` header for authenticating with the GraphQL API.

Client Configuration

To allow clients like Cursor or Claude Desktop to use the tools provided by this server, you need to configure them to run the `npx` command.

Cursor

1. Go to Cursor MCP Settings (Cursor > Settings > Cursor Settings > MCP)

2. Go to + Add new global MCP server

3. Add the following to your Cursor MCP configuration:

{
     "mcpServers": {
       "mcp4gql": {
         "command": "npx",
         "type": "stdio",
         "args": ["-y", "mcp4gql"],
         "env": {
           "GRAPHQL_ENDPOINT": "YOUR_GRAPHQL_ENDPOINT_URL",
           "AUTH_TOKEN": "YOUR_OPTIONAL_AUTH_TOKEN"
         }
       }
     }
   }

Claude Desktop

1. Open Claude Desktop settings (Claude > Settings).

2. Go to Developer > Edit Config.

3. Add to the config:

{
      "mcpServers": {
        "mcp4gql": {
          "command": "npx",
          "args": ["-y", "mcp4gql"],
          "env": {
            "GRAPHQL_ENDPOINT": "YOUR_GRAPHQL_ENDPOINT_URL",
            "AUTH_TOKEN": "YOUR_OPTIONAL_AUTH_TOKEN"
          }
        }
      }
    }

Once configured, the MCP client should be able to list and call the `introspectGraphQLSchema` and `executeGraphQLOperation` tools provided by this server when relevant. Remember to set the required environment variables (`GRAPHQL_ENDPOINT` and optionally `AUTH_TOKEN`) in the configuration so the server can connect to your API.