gqai

graphql → ai

gqai is a lightweight proxy that exposes GraphQL operations as Model Context Protocol (MCP) tools for AI like Claude, Cursor, and ChatGPT.
Define tools using regular GraphQL queries/mutations against your GraphQL backend, and gqai automatically generates an MCP server for you.

🔌 Powered by your GraphQL backend
⚙️ Driven by .graphqlrc.yml + plain .graphql files

✨ Features

• 🧰 Define tools using GraphQL operations

• 🗂 Automatically discover operations from .graphqlrc.yml

• 🧾 Tool metadata compatible with OpenAI function calling / MCP

Related MCP server: tavily-search

🛠️ Installation

🚀 Quick Start

1. Create a .graphqlrc.yml:

This file tells gqai where to find your GraphQL schema and operations.

Note: The

2. Add a GraphQL operation

get_all_films.graphql:

3. Add gqai to your mcp.json file:

That's it! Your AI model can now call the get_all_films tool.

Usage

Configuration

GraphQL Config

The graphql config file is a YAML file that defines the GraphQL endpoint and the operations you want to expose as tools. It should be named .graphqlrc.yml and placed in the root of your project.

The schema field specifies the GraphQL endpoint, and the documents field specifies the directory where your GraphQL operations are located.

In this example, the operations directory contains all the GraphQL operations you want to expose as tools. Operations are defined in .graphql files, and gqai will automatically discover them.

Headers

You can also specify headers to be sent with each request to the GraphQL endpoint. This is useful for authentication or other custom headers.

Using Environment Variables in Headers

You can reference environment variables in header values using the ${VARNAME} syntax. For example:

You can also provide a default value using the ${VARNAME:-default} syntax:

When gqai loads the config, it will substitute ${MY_AUTH_TOKEN} with the value of the MY_AUTH_TOKEN environment variable, or use default-token if the variable is not set. This allows you to keep secrets out of your config files.

If the environment variable is not set and no default is provided, the value will be left as-is.

Using Environment Variables in Config

You can use environment variables in any part of your .graphqlrc.yml config: schema URLs, document paths, include/exclude globs, and header values. Use ${VARNAME} or ${VARNAME:-default} syntax:

gqai will substitute these with the value of the environment variable, or use the default if not set. This keeps secrets and environment-specific paths out of your config files.

MCP Configuration

Claude Desktop

To use gqai with Claude Desktop, you need to add the following configuration to your mcp.json file:

🧪 CLI Testing

Call a tool via CLI to test:

This will execute the get_all_films tool and print the result.

Call a tool with arguments:

Create a GraphQL operation that takes arguments, and these will be the tool inputs:

get_film_by_id.graphql:

Call the tool with arguments:

This will execute the get_film_by_id tool with the provided arguments.

Development

Prerequisites

• Go 1.20+

Build

Test

Format

Run MCP server

Run CLI

About GQAI

🤖 Why gqai?

gqai makes it easy to turn your GraphQL backend into a model-ready tool layer — no code, no extra infra. Just define your operations and let AI call them.

📜 License

MIT — fork it, build on it, all the things.

👋 Author

Made with ❤️ and 🤖vibes by Stephen Spalding && <your-name-here>