Github Graphql MCP Server

What QuentinCody/github-graphql-mcp-server MCP server does

QuentinCody/github-graphql-mcp-server MCP server gives an MCP-compatible client one tool for sending GraphQL operations to GitHub's API. The operation can be a query for reading data or a mutation for changing data. Because the tool accepts arbitrary GraphQL, the requested fields and resource types are determined by the operation rather than by a small collection of predefined commands.

The repository documentation demonstrates operations for reading repository details, searching repositories, and retrieving user information. The same approach can be used for other resources supported by GitHub's GraphQL schema, provided the token has the required permissions and the operation is valid.

How it works

The Python process reads the GitHub token from the GITHUB_TOKEN environment variable and uses it to authenticate requests to GitHub's GraphQL API. A client sends a GraphQL document through the MCP tool, optionally alongside a JSON object containing variables. The server forwards the operation and returns the API response, including error information when GitHub rejects the request or the GraphQL document is invalid.

This design leaves schema selection and query construction to the calling agent. For example, a repository query can accept owner and name variables, while a search query can accept a search expression and result count.

Setup and configuration

QuentinCody/github-graphql-mcp-server requires Python 3.10 or newer, a GitHub personal access token, and the dependencies listed in requirements.txt. The documented installation path is to clone the repository, create and activate a virtual environment, and run pip install -r requirements.txt.

Run the script with the token in its environment:

GITHUB_TOKEN=your_github_token_here python github_graphql_mcp_server.py

For Claude Desktop, configure the server with the absolute path to the virtual environment's Python executable and the absolute path to github_graphql_mcp_server.py. The example configuration also sets the repository as the process working directory and supplies GITHUB_TOKEN in the server environment. Restart Claude Desktop after changing its configuration.

Tools and capabilities

The server exposes one MCP tool rather than separate tools for repositories, issues, pull requests, or users. That tool supports:

• Arbitrary GitHub GraphQL queries
• GraphQL mutations
• Variables supplied separately from the operation
• Error reporting for failed requests or invalid operations

This makes the server suitable when an agent needs fields or operations beyond a fixed, repository-specific tool catalog. Query validity, available fields, permissions, and mutation behavior depend on GitHub's current GraphQL schema and the supplied token.

Limitations and notes

A valid GitHub token is required for the documented setup. Tokens must have permissions appropriate to the requested operation. GitHub rate limits can restrict repeated requests, even when the MCP server itself is running correctly.

Common setup failures include using an incorrect Python path, skipping dependency installation, omitting GITHUB_TOKEN, or sending a query that does not match GitHub's schema. The README recommends checking server logs, confirming the virtual environment is active, using absolute paths in Claude Desktop, and verifying token permissions when troubleshooting. The project is licensed under MIT.