gqai is a lightweight proxy tool designed to convert any GraphQL endpoint into a set of MCP (Model Context Protocol) tools for invocation by AI models such as Claude, Cursor, ChatGPT, etc. It is powered by the user's GraphQL backend and defines tools through a .graphqlrc.yml configuration file and ordinary .graphql files.
Main capabilities:
- Use regular GraphQL queries and mutations to define tools.
- Automatically discover operations from .graphqlrc.yml.
- The generated tool metadata is compatible with OpenAI function calling and MCP.
Usage:
- Create a .graphqlrc.yml file in the project root directory, specifying the GraphQL schema endpoint and the operations document directory. The schema parameter must point to a live server that can execute operations, not a static schema file.
- Add GraphQL operation files, such as get_all_films.graphql, with content consisting of regular GraphQL queries.
- Add the gqai configuration to the mcp.json file to register it as an MCP server.
- After configuration is complete, the AI model can invoke the defined tools, such as get_all_films.
Configuration details:
- The schema field in .graphqlrc.yml specifies the GraphQL endpoint, and the documents field specifies the directory where the GraphQL operation files are located. gqai automatically discovers operations in .graphql files under that directory.
- Request headers can be configured for authentication or other custom needs.
- Environment variables are supported in the configuration, with the syntax ${VARNAME} or ${VARNAME:-default} (providing a default value). Environment variables can be used for the schema URL, document paths, include/exclude glob patterns, and header values, as well as any other part, which helps keep secrets and environment-related paths out of the configuration file. If an environment variable is not set and no default value is provided, it is kept as is.
Tool input: If a GraphQL operation has parameters, these parameters will serve as the tool's input. For example, after definingget_film_by_id.graphql, the corresponding parameters can be passed in when invoking the tool to execute it.
Use cases:
- Quickly expose an existing GraphQL backend as AI-callable tools without writing additional code or deploying additional infrastructure.
- Integrate with MCP-supporting AI clients such as Claude Desktop.
Limitations:
- The schema must be a live server, not a static schema file.
- It relies on .graphqlrc.yml and .graphql files to define operations.
- Other unmentioned features, fees, pricing, platform support, or effects are not currently provided.
License: MIT, free to fork and build.
