mcp-graphql-forge

A lightweight, configuration-driven MCP server that exposes curated GraphQL queries as modular tools, enabling intentional API interactions from your agents.

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

View docs

Command

claude mcp add --transport stdio unitvectory-labs-mcp-graphql-forge go install github.com/UnitVectorY-Labs/mcp-graphql-forge@latest \
  --env FORGE_DEBUG="true to enable debug logging (optional)" \
  --env FORGE_CONFIG="Path to your forge.yaml configuration folder (optional if using --forgeConfig)"

How to use

mcp-graphql-forge is a lightweight, configuration-driven MCP server that turns a GraphQL endpoint into a suite of modular tools. Each tool is defined in YAML and maps a GraphQL query and its variables to a named tool that clients can invoke via MCP. The server reads a forge.yaml file to know the GraphQL endpoint and token configuration, and additional YAML files in the same folder define the individual tools, their inputs, and how to format the output (raw, json, or toon). You can expose as many tools as you want as long as you provide the corresponding GraphQL query and input definitions, making it easy to compose a minimal, secure, and purpose-built interface to a GraphQL API for your agents. Tools support inputs with string or number types and may include optional annotations to guide behavior like readOnly, destructive, and idempotent hints, which help downstream clients reason about usage.

How to install

Prerequisites:

Go installed (1.20+ recommended)
Git

Install:

Install the MCP server binary from source (latest):

go install github.com/UnitVectorY-Labs/mcp-graphql-forge@latest

Verify installation:

which mcp-graphql-forge
# or check GOPATH/bin/mcp-graphql-forge

Prepare configuration folder:

Create a forge.yaml with the GraphQL endpoint URL and optional token command if needed.
Add YAML files for each tool you want to expose under the same folder.

Run in stdio mode (default) or enable HTTP mode with --http after building the binary:

# Example: run with HTTP on port 8080
mcp-graphql-forge --http 8080

Optional: Set environment variables FORGE_CONFIG and FORGE_DEBUG to control config loading and debug logging.

Notes:

The server expects a forge.yaml for the common configuration and separate YAML files for each tool.
If token_command is provided, the server will use it to obtain the Bearer token for Authorization when talking to the GraphQL endpoint.

Additional notes

Tips and common issues:

Ensure the GraphQL endpoint URL is reachable from the host running the MCP server.
If you don’t provide a token_command, Authorization headers from MCP requests may be forwarded to the GraphQL endpoint depending on configuration.
Use FORGE_DEBUG or --forgeDebug to diagnose token retrieval and HTTP traffic when troubleshooting.
Output format can be raw, json, or toon; consider using json or toon to reduce token usage when piping results into LLMs.
The forge.yaml configuration supports env and env_passthrough to tailor token acquisition and client environment handling.
Each tool’s inputs must align with the GraphQL variables expected by its query; omit optional inputs if not required by the query.