GitHub GraphQL API

You can query and explore the GitHub GraphQL API using an MCP server. This server lets you browse the GraphQL schema, view documentation for types and fields, and execute GraphQL queries through MCP clients, enabling precise data retrieval and efficient token usage.

How to use

Connect to the MCP server with an MCP client (such as Claude AI). You can query root type documentation, inspect fields for specific types, get type documentation, and execute GraphQL queries against the GitHub GraphQL API. Use the provided tools to perform targeted data retrieval and compose optimized queries that reduce unnecessary data transfer.

How to install

Prerequisites you need before installing:

• Python 3.10 or higher
• GitHub personal access token (for API access)
• Poetry (recommended dependency management tool) or an alternative virtual environment method

# Clone the project repository
git clone https://github.com/wanzunz/github_graphql_api_mcp.git
cd github_graphql_api_mcp

# Install dependencies with Poetry
poetry install

# Activate the virtual environment
poetry shell

If you don’t use Poetry, create and activate a virtual environment, then install dependencies in editable mode.

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/MacOS
# Windows: .venv\Scripts\activate

# Install dependencies in editable mode
pip install -e .

Configure your GitHub token in a local environment file.

GITHUB_TOKEN="your_github_token_here"

Configuration and running the server

You can start the MCP server by running the Python script directly or using a configurable MCP launch command suitable for integration with MCP clients like Claude. Use one of the following approaches depending on your workflow.

# Start directly (assumes you are in the project directory and the environment is prepared)
python github_graphql_api_mcp_server.py

# Start via a configurable MCP launcher (example for Claude Desktop integration)
# Replace <project path> with your actual project path
python --directory <project path> run github_graphql_api_mcp_server.py

Additional notes

Environment variables are stored in a local .env file and should not be committed to version control. The token you provide should have appropriate permissions for GitHub API access. When connecting from an MCP client, ensure you have started the server with the correct working directory and that the client is configured to point at the running MCP instance.

If you are using Claude Desktop, you can configure the MCP server with a JSON entry that specifies the Python command and the arguments to start the server, enabling one-click startup from the client.

Security and usage tips

Keep your GitHub token secret. Do not expose it in public repositories or shared configurations. Monitor API usage to stay within GitHub’s rate limits and adjust query patterns to fetch only the needed fields for optimal performance.

Examples

Run a simple query through an MCP client after the server is up to fetch viewer login and name.

Troubleshooting

If the server fails to start, verify that Python 3.10+ is available, the virtual environment is activated, and GITHUB_TOKEN is correctly configured in your environment. Check that the port or endpoint used by your MCP client is accessible and that no firewall blocks the connection.

Available tools

print_type_field

Query fields of GitHub GraphQL schema root types to inspect available data fields.

graphql_schema_root_type

Get documentation for root types such as QUERY and MUTATION to understand available operations.

graphql_schema_type

Query documentation for specific GraphQL types to learn fields and constraints.

call_github_graphql

Execute GitHub GraphQL API queries directly and retrieve precise data.