iChebbi/graphql-mcp-tools

GraphQL MCP Tools Server

An MCP server (Model Context Protocol) that introspects a GraphQL endpoint and exposes each Query and Mutation field as a separate MCP tool.

• Uses @modelcontextprotocol/sdk
• Implemented in TypeScript
• GraphQL endpoint and optional Authorization header are provided via CLI arguments or environment variables
• Supports stdio and HTTP (SSE/Streamable HTTP) transports

Installation

yarn install
yarn build

Usage

The server supports two transport modes:

1. Stdio Transport (Default)

Run over stdio (as MCP servers typically do), configuring the GraphQL endpoint:

# Using env vars
GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql yarn start

# Or using CLI args (note the `--` separator for script args)
yarn start -- --endpoint https://rickandmortyapi.com/graphql

# With Authorization header (if your API requires it)
GRAPHQL_ENDPOINT=https://your.api/graphql GRAPHQL_AUTHORIZATION="Bearer <token>" yarn start
# Or
yarn start -- --endpoint https://your.api/graphql --authorization "Bearer <token>"

2. HTTP Transport with SSE (Streamable HTTP)

Run as an HTTP server with Server-Sent Events for streaming communication:

# Using env vars with 'sse' transport
GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql MCP_TRANSPORT=sse yarn start

# Using env vars with 'streamable-http' transport (alias for sse)
GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql MCP_TRANSPORT=streamable-http yarn start

# Or using CLI args with 'sse'
yarn start -- --endpoint https://rickandmortyapi.com/graphql --transport sse

# Or using CLI args with 'streamable-http'
yarn start -- --endpoint https://rickandmortyapi.com/graphql --transport streamable-http

# Custom host and port
yarn start -- --endpoint https://rickandmortyapi.com/graphql --transport streamable-http --host 0.0.0.0 --port 8080

# Or using env vars
GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql MCP_TRANSPORT=streamable-http MCP_HOST=0.0.0.0 MCP_PORT=8080 yarn start

When using SSE or streamable-http transport:

• Server will listen on the specified host and port (defaults to localhost:3000)
• Connect to /mcp endpoint to establish MCP connection
• POST messages to /message?sessionId=<session_id> endpoint
• Visit the server URL in a browser for connection information

Configuration Options

When the server starts, it will introspect the given endpoint and register one MCP tool per field under Query. Mutation tools are hidden by default for safety.

• query_<fieldName> for queries
• mutation_<fieldName> for mutations (only if enabled)

Input schema is derived from the GraphQL field arguments. Output is returned as JSON content from the GraphQL response.

Enabling mutations

By default, mutation tools are hidden. To expose them:

• CLI flag: add --enable-mutations (or --mutations)
• Env var: set GRAPHQL_ENABLE_MUTATIONS=true

Examples:

# Using CLI
npm start -- --endpoint https://rickandmortyapi.com/graphql --enable-mutations

# Using env var
GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql GRAPHQL_ENABLE_MUTATIONS=true npm start

Testing with Rick and Morty API

The public Rick and Morty GraphQL API can be used for testing:

GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql npm start

You should see tools like query_character, query_characters, etc. Invoking query_character with an input { "id": 1 } will perform the corresponding GraphQL query and return the JSON result.

Development

# Stdio transport (default)
yarn dev -- --endpoint https://rickandmortyapi.com/graphql

# HTTP transport for web-based testing (sse or streamable-http)
yarn dev -- --endpoint https://rickandmortyapi.com/graphql --transport streamable-http --port 3001

Testing

This repository includes simple integration tests using Node's built-in test runner.

yarn test

By default, tests use the public Rick and Morty GraphQL endpoint. You can override it with:

GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql yarn test

Notes

• The server infers a minimal selection set when the return type is an object (it requests __typename by default). For richer responses, you can adjust the implementation to build deeper selections or define per-field selections.
• Authorization header is passed through unchanged if provided.

Using with LLM clients (MCP)

This server supports MCP over stdio and HTTP (SSE/Streamable HTTP) transports. Any MCP-aware client can connect using either method.

Stdio Transport (Traditional)

• Command to run the server (from this repo):
  • Build once: yarn build
  • Run: node dist/server.js
  • Example with env vars: GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql node dist/server.js

HTTP Transport with SSE (Streamable HTTP)

• Command to run the server:
  • Build once: yarn build
  • Run: node dist/server.js --transport streamable-http --port 3000
  • Example: GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql node dist/server.js --transport streamable-http
  • Access via HTTP at http://localhost:3000/mcp for MCP connection

Claude Desktop

Claude Desktop supports MCP via the mcpServers field in its config file.

1. Locate your claude_desktop_config.json:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Add an entry under mcpServers to launch this server.

{
  "mcpServers": {
    "graphql-mcp": {
      "command": "node",
      "args": [
        "/absolute/path/to/graphql-mcp-tools/dist/server.js"
      ],
      "env": {
        "GRAPHQL_ENDPOINT": "https://rickandmortyapi.com/graphql",
        "GRAPHQL_ENABLE_MUTATIONS": "true" // optional; enable if you want mutation tools
      }
    }
  }
}

Notes:

• You do NOT need to move the project next to the LLM client’s config. Just point to the built script using either cwd + relative path or an absolute path.
• Ensure you ran yarn install && yarn build so dist/server.js exists.
• Restart Claude Desktop after editing the config. The tools should appear under the "graphql-mcp" server; one tool per GraphQL query/mutation (e.g., query_character).
• To point at a protected API, add GRAPHQL_AUTHORIZATION (or AUTHORIZATION) to env.

MCP Inspector (for quick testing)

You can test this server with the official Inspector UI.

• Install and run (one-time build first):
  • yarn build
  • npx @modelcontextprotocol/inspector --command "node" -- "/absolute/path/to/graphql-mcp-tools/dist/server.js" --endpoint https://rickandmortyapi.com/graphql

Notes:

• If you prefer, you can keep using a relative dist/server.js by running the Inspector from the project root (so cwd points at the repo). Using an absolute path avoids cwd ambiguity.

This opens a local UI where you can invoke the auto-generated tools.

Gemini CLI and other MCP-aware CLIs

• Status: As of 2025-08-24, some Gemini-related CLIs may not yet provide first-party MCP integration. Community CLIs and other LLM CLIs increasingly support launching MCP servers via a stdio command. Consult your CLI’s documentation for the exact flags to register an MCP server.
• General guidance: Configure your CLI to launch this server with the command and environment variables, e.g.:
  • Command: node
  • Args: ["/absolute/path/to/graphql-mcp-tools/dist/server.js"]
  • Env: GRAPHQL_ENDPOINT=https://rickandmortyapi.com/graphql (and GRAPHQL_AUTHORIZATION if needed)
  • Working directory: optional if you use an absolute path; required if you pass a relative path like "dist/server.js".

If your CLI supports passing CLI args instead of env vars, you can use:

node /absolute/path/to/graphql-mcp-tools/dist/server.js --endpoint https://rickandmortyapi.com/graphql --authorization "Bearer <token>"

Once registered, the client should list tools like query_character, query_characters, etc., each corresponding to a GraphQL field.

Introspection tool

This server also exposes an extra tool to let clients fetch the schema:

• Tool name: introspect_schema
• Arguments:
  • format: "sdl" (default) or "json"

Examples:

• Get SDL text: call introspect_schema with {}
• Get introspection JSON: call introspect_schema with { "format": "json" }

Results are returned as plain text content (for SDL) or JSON stringified as text (for JSON), to maximize compatibility with MCP clients.