GitHub

This MCP server lets you explore the GitHub GraphQL API schema and execute GraphQL queries through MCP clients. It provides structured access to root types, type documentation, and direct query execution to help you retrieve precisely what you need with minimal token usage.

How to use

Connect to the MCP server with your MCP client to start exploring the GitHub GraphQL API and running queries. You can: query root type documentation, inspect specific type documentation, and execute GraphQL queries to fetch repository, issue, user, PR, and dependency data. Use the available tools to navigate the schema and send queries that return only the fields you need.

How to install

Prerequisites you need before installing: Python 3.10 or higher, a GitHub personal access token, and Poetry (recommended) for dependency management.

Steps to install and run locally:

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

# 2. Install dependencies with Poetry (recommended)
# If you haven't installed Poetry yet, install it first:
# curl -sSL https://install.python-poetry.org | python3 -

poetry install
poetry shell

# If you don't use Poetry, use a virtual environment
python -m venv .venv
source .venv/bin/activate  # Linux/MacOS
# Windows: \.venv\Scripts\activate

pip install -e .

Additional setup and configuration

Configure your GitHub token in a .env file to enable access to the GitHub API. Create the file with your token as shown below and ensure it is not committed to version control.

GITHUB_TOKEN="your_github_token_here"

Starting the MCP server and connecting from a client

Run the MCP server using Python. Once running, connect your MCP client (for example Claude AI) and begin querying the GitHub GraphQL API.

python github_graphql_api_mcp_server.py

Configuration for Claude Desktop (MCP client integration)

You can configure the MCP server in Claude Desktop for one-click startup using the directory-based run command.

{
  "mcpServers": {
    "github_mcp": {
      "command": "<your Python interpreter path>",
      "args": [
        "--directory",
        "<project path>",
        "run",
        "github_graphql_api_mcp_server.py"
      ]
    }
  }
}

Available MCP connection method (stdio)

If you prefer running the server locally via your Python interpreter, use the following stdio configuration. This starts the server directly from your environment.

{
  "type": "stdio",
  "name": "github_mcp",
  "command": "/usr/bin/python3",
  "args": [
    "--directory",
    "/home/user/projects/github_graphql_api_mcp/",
    "run",
    "github_graphql_api_mcp_server.py"
  ]
}

Available tools

print_type_field

Query fields of GitHub GraphQL schema root types to discover available fields for a given type.

graphql_schema_root_type

Get documentation for root types (Query/Mutation) to understand available operations.

graphql_schema_type

Query documentation for specific GraphQL types to learn field details and constraints.

call_github_graphql

Execute GitHub GraphQL API queries directly and retrieve precise data.