mcp4gql - GraphQL

You can connect your MCP clients to a target GraphQL API through a dedicated MCP server. This bridge lets you introspect the GraphQL schema and execute operations against the API from MCP-enabled tools and clients, enabling seamless data access and mutations without embedding API logic in each client.

How to use

Use an MCP client (such as Cursor or Claude Desktop) to load the mcp4gql server as a new MCP source. The server runs through standard in/out (stdio) communication, so your client will start the server process and exchange messages over the configured channels. Once connected, you can list and invoke the provided tools to work with your GraphQL API: introspectGraphQLSchema to fetch the GraphQL schema, and executeGraphQLOperation to run arbitrary queries or mutations.

How to install

Prerequisites: install Node.js (version 14 or newer) and npm on your system.

Install or run the MCP server using the npm ecosystem. The server is intended to be invoked by MCP clients via a standard command, so you will execute the following in your terminal with the required environment variables set.

# Ensure you have Node.js and npm installed
node -v
npm -v

# Run the MCP server via npx, with required environment variables
GRAPHQL_ENDPOINT=https://your-graphql-endpoint.example/graphql \
AUTH_TOKEN=YOUR_AUTH_TOKEN \
npx -y mcp4gql

Additional configuration and tools

Configure your MCP clients to use the stdio-based server configuration shown below. The client will start the server process and communicate through the configured arguments and environment variables.

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

Configuration and environment variables

Set the following environment variables to enable the server to connect to your GraphQL API. The AUTH_TOKEN variable is optional if your API does not require bearer authentication.

Security notes

Treat GRAPHQL_ENDPOINT and AUTH_TOKEN as sensitive credentials. Use secure storage and restrict access to entities that should be allowed to interact with your GraphQL API. Rotate tokens regularly and limit token scopes to what is necessary for MCP tooling.

Troubleshooting

If tools do not appear in your MCP client, verify that the environment variables are set correctly and that the target GraphQL API is reachable from the host running the MCP server. Check that the MCP client is configured to use the stdio channel with the same command and environment variables described above.

Available tools

introspectGraphQLSchema

Fetches the target GraphQL API schema using introspection so clients can discover available types, queries, and mutations.

executeGraphQLOperation

Executes arbitrary GraphQL queries or mutations against the target API, accepting a GraphQL query string, optional variables, and an optional operationName.