MCP Graphql Forge

🚀 mcp-graphql-forge

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

🚀 Quick Start

mcp-graphql-forge allows you to transform any GraphQL endpoint into an MCP server. Its tools are defined by YAML files, which specify GraphQL queries and their parameters. This enables you to create a modular, secure, and easily extensible server without modifying your application code.

✨ Features

Configuration

The server is configured using environment variables and YAML files.

Environment Variables

• FORGE_CONFIG: Specifies the folder path containing the YAML configuration file (forge.yaml) and tool definitions. The default is the current directory (.), if not set.
• FORGE_DEBUG: If set to true (case-insensitive), enables detailed debug logging to stderr, including the obtained tokens and the full HTTP request/response of GraphQL calls. The default is false.

forge.yaml

The configuration folder uses a special configuration file forge.yaml, which specifies general configuration attributes.

The following attributes can be specified in the file:

• name: The name of the MCP server
• version: The version of the MCP server
• url: The URL of the GraphQL endpoint
• token_command: The command used to request the Bearer token for the Authorization header (optional)

An example configuration is as follows:

name: "ExampleServer"
version: "0.1.0"
url: "https://api.github.com/graphql"
token_command: "gh auth token"

Tool Configuration

All other YAML files in the folder are considered 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 be executed
• inputs: A list of inputs for the MCP tool that define the inputs and pass them to 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 used by the MCP tool
  • required: A boolean value specifying whether the attribute is required

An example configuration is as follows:

name: "getUser"
description: "Get the basic information of a user, including their name, URL, and location, through `login`."
query: |
  query ($login: String!) {
    user(login: $login) {
      id
      name
      url
      location
    }
  }
inputs:
  - name: "login"
    type: "string"
    description: "The `login` that uniquely identifies their account."
    required: true

🔧 Technical Details

Limitations

• Each mcp-graphql-forge instance can only be used with a single GraphQL server at a single URL.
• All requests use the same Authorization header in the form of a Bearer token.
• GraphQL queries are all exposed as tools, not resources. This is because not all current MCP clients support resources.