UnitVectorY-Labs/mcp-graphql-forge

A lightweight, configuration-driven MCP server that exposes curated GraphQL queries as modular tools, enabling intentional API interactions from your agents.
Purpose
mcp-graphql-forge lets you turn any GraphQL endpoint into an MCP server whose tools are defined in YAML files that specify the GraphQL queries and their parameters. This allows you to create a modular, secure, and minimal server that can be easily extended without modifying the application code.
Releases
All official versions of **mcp-graphql-forge** are published on GitHub Releases. Since this MCP server is written in Go, each release provides pre-compiled executables for macOS, Linux, and Windows—ready to download and run.
Alternatively, if you have Go installed, you can install **mcp-graphql-forge** directly from source using the following command:
Configuration
The server is configured using command line parameters, environment variables, and YAML files.
Command Line Parameters
- --forgeConfig: Specifies the path to the folder containing the YAML configuration files (forge.yaml and tool definitions). If set, this takes precedence over the FORGE_CONFIG environment variable. If neither is set, the application will return an error and exit.
- --forgeDebug: If provided, enables detailed debug logging to stderr, including the obtained token and the full HTTP request/response for GraphQL calls. If set, this takes precedence over the FORGE_DEBUG environment variable.
Environment Variables
- FORGE_CONFIG: Specifies the path to the folder containing the YAML configuration files (forge.yaml and tool definitions). Used if --forgeConfig is not set.
- FORGE_DEBUG: If set to true (case-insensitive), enables detailed debug logging to stderr, including the obtained token and the full HTTP request/response for GraphQL calls. Used if --forgeDebug is not set.
forge.yaml
The configuration folder uses a special configuration file forge.yaml that specifies the common configuration attributes.
The following attributes can be specified in the file:
- name: The name of the MCP server
- url: The URL of the GraphQL endpoint
- token_command: The command to use to request the Bearer token for the Authorization header (optional)
- env: A map of environment variables to pass to the token command (optional)
- env_passthrough: If set to true, passes all environment variables used when invoking mcp-graphql-forge to the token command; if used in conjunction with env, the variables from env will take precedence (optional, defaults to false)
An example configuration would look like:
Tool Configuration
All other YAML files located in the folder are treated as configuration files. Each YAML file defines a tool for the MCP server.
The following attributes can be specified in the file:
- name: The name of the MCP tool
- description: The description of the MCP tool
- query: The GraphQL query to execute
- inputs: The list of inputs defined by the MCP tool and passed into the GraphQL query as variables
- name: The name of the input
- type: The parameter type; can be 'string' or 'number'
- description: The description of the parameter for the MCP tool to use
- required: Boolean value specifying if the attribute is required