mcp-graphql

library2.0.4jsnpmunverified

mcp-graphql is a Model Context Protocol server that enables LLMs to interact with GraphQL APIs. Version 2.0.4 is the latest stable release. It provides schema introspection and query execution tools, allowing AI agents to discover and query GraphQL endpoints dynamically. Key differentiators: supports local schema files as alternative to live introspection, disables mutations by default for safety, and uses environment variables for configuration (command-line args removed in v1.0.0). Other MCP GraphQL servers exist but this one focuses on simplicity and security with minimal setup.

ai-ml api

npm install mcp-graphql

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · MCP-GRAPHQL

mcp-graphql

ai-mljavascriptv2.0.4

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default import

✓ import mcpGraphql from 'mcp-graphql'

✗ const mcpGraphql = require('mcp-graphql')

Package uses ESM. CommonJS require is not supported; type: module in package.json.

N/A

✓ npx mcp-graphql

✗ mcp-graphql

Run via npx; the package does not export any programmatic API, only a CLI.

N/A

✓ ENDPOINT=http://localhost:3000/graphql npx mcp-graphql

✗ npx mcp-graphql --endpoint http://...

As of v1.0.0, configuration is via environment variables only, not command-line arguments.

Shows how to start the MCP server with environment variables and connect using the SDK to list tools and call introspect-schema.

ENDPOINT=http://localhost:3000/graphql npx mcp-graphql & sleep 2 # In another terminal, connect to the MCP server (example using generic MCP client) # The server exposes 'introspect-schema' and 'query-graphql' tools. # Use an MCP client to call tools, e.g., with @modelcontextprotocol/sdk: import { Client } from '@modelcontextprotocol/sdk/client/index.js'; const client = new Client({ name: "test", version: "1.0.0" }); await client.connect(new StdioClientTransport({ command: "npx", args: ["mcp-graphql"], env: { ENDPOINT: "http://localhost:3000/graphql" } })); const tools = await client.listTools(); console.log(tools); // Then call introspect-schema or query-graphql const result = await client.callTool({ name: "introspect-schema", arguments: {} }); console.log(result);

Debug

Known issues

breakingAs of version 1.0.0, command line arguments have been replaced with environment variables. Use ENDPOINT, HEADERS, etc. instead of --endpoint.

fix

Switch to environment variables: ENDPOINT=http://... npx mcp-graphql

affects: <1.0.0

deprecatedUsing local schema file (SCHEMA env var) may be deprecated in future versions; preference is introspection.

fix

If you rely on SCHEMA, consider migrating to live introspection or provide a local file path.

affects: >=1.0.0 <2.0.0

gotchaMutations are disabled by default. To enable them, set ALLOW_MUTATIONS=true. Security risk: LLM can modify data.

fix

Set ALLOW_MUTATIONS=true in environment if need mutations, otherwise leave false.

affects: >=1.0.0

gotchaHEADERS environment variable must be a valid JSON string. Improper quoting can cause parse errors.

fix

Use single quotes around JSON: HEADERS='{"Authorization":"Bearer token"}'

affects: >=1.0.0

gotchaIf ENDPOINT is not set, defaults to http://localhost:4000/graphql which may not be intended.

fix

Always set ENDPOINT explicitly.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'mcp-graphql'

Running without npx or missing package installation.

fix

Use npx mcp-graphql or install globally: npm install -g mcp-graphql && mcp-graphql

Error: ENDPOINT is required

ENDPOINT environment variable not set.

fix

Set ENDPOINT environment variable, e.g., ENDPOINT=http://localhost:3000/graphql npx mcp-graphql

SyntaxError: Unexpected token } in JSON at position ...

HEADERS environment variable is not valid JSON.

fix

Ensure HEADERS is a valid JSON string, e.g., HEADERS='{"Authorization":"Bearer token"}'

Upgrade

Version history

2.0.4latest on npm

Audit

Dependencies

@modelcontextprotocol/sdkrequiredProvides the MCP server framework and protocol handling.

graphqlrequiredUsed for parsing GraphQL schemas and executing queries.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/blurrah/mcp-graphql ↗

packagemcp-graphql ↗

homepagehttps://github.com/blurrah/mcp-graphql#readme ↗