Github Graphql MCP Server

🚀 GitHub GraphQL MCP Server

A Model Context Protocol (MCP) server that provides access to the GitHub GraphQL API. This server offers a tool to execute arbitrary GraphQL queries and mutations against GitHub's API.

🚀 Quick Start

This is a Model Context Protocol (MCP) server that enables access to the GitHub GraphQL API. It allows users to perform any GraphQL queries and mutations on GitHub's API.

✨ Features

• Execute any GraphQL query against the GitHub API.
• Comprehensive error handling and reporting.
• Detailed documentation with example queries.
• Support for variables in GraphQL operations.

📦 Installation

Prerequisites

• Python 3.10 or higher.
• A GitHub Personal Access Token (PAT).

Steps

1. Clone this repository.
2. Set up a virtual environment (recommended):

   # On macOS/Linux
   python3 -m venv .venv
   source .venv/bin/activate
   
   # On Windows
   python -m venv .venv
   .venv\Scripts\activate
   

3. Install the dependencies:

   pip install -r requirements.txt
   

💻 Usage Examples

Running the Server

# If using a virtual environment, make sure it's activated
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the server with your GitHub token
GITHUB_TOKEN=your_github_token_here python github_graphql_mcp_server.py

Configuration with Claude Desktop

Add the following to your Claude Desktop configuration file:

{
  "github-graphql": {
    "command": "/absolute/path/to/your/.venv/bin/python",
    "args": [
        "/absolute/path/to/github_graphql_mcp_server.py"
    ],
    "options": {
        "cwd": "/absolute/path/to/repository"
    },
    "env": {
        "GITHUB_TOKEN": "your_github_token_here"
    }
  }
}

Replace /absolute/path/to/ with the actual path to your server files and add your GitHub token.

Basic Usage

Getting Repository Information

query GetRepo($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    name
    description
    stargazerCount
    url
    createdAt
    owner {
      login
      avatarUrl
    }
  }
}

Variables:

{
  "owner": "octocat",
  "name": "Hello-World"
}

Searching for Repositories

query SearchRepos($query: String!, $first: Int!) {
  search(query: $query, type: REPOSITORY, first: $first) {
    repositoryCount
    edges {
      node {
        ... on Repository {
          name
          owner { login }
          description
          stargazerCount
          url
        }
      }
    }
  }
}

Variables:

{
  "query": "language:python stars:1000",
  "first": 5
}

Getting User Information

query GetUserInfo($login: String!) {
  user(login: $login) {
    name
    login
    bio
    avatarUrl
    followers {
      totalCount
    }
    repositories(first: 5, orderBy: {field: STARGAZERS, direction: DESC}) {
      nodes {
        name
        description
        stargazerCount
      }
    }
  }
}

Variables:

{
  "login": "octocat"
}

📚 Documentation

GitHub API Rate Limits

Be aware of GitHub's API rate limits:

• Authenticated requests: 5,000 requests per hour.
• Unauthenticated requests: 60 requests per hour.

Troubleshooting

If you encounter issues:

1. Check if your GitHub token has the correct permissions.
2. Ensure your virtual environment is set up and activated correctly.
3. Make sure your token is set correctly in the environment variables.
4. If using Claude Desktop, ensure the Python path is correct (use the absolute path of the virtual environment Python).
5. Check the error messages in the server logs.
6. Ensure your GraphQL queries are valid against GitHub's schema.
7. Restart Claude Desktop after making configuration changes.

Common Errors

spawn python ENOENT

• This error indicates that the Python executable cannot be found.
• Solution: Use the absolute path of the Python executable in the virtual environment (e.g., /path/to/your/.venv/bin/python).

ModuleNotFoundError: No module named 'httpx' (or other packages)

• Solution: Run pip install -r requirements.txt to install the missing dependencies.

GITHUB_TOKEN cannot be empty or similar errors

• Ensure a valid GitHub token is set in the environment variables.