github-graphql-mcp-server
The GitHub GraphQL MCP Server is designed to enable users to execute arbitrary GraphQL queries and mutations against GitHub's API. It features comprehensive error handling and detailed documentation. It is tailored for users who need to interact with GitHub's GraphQL API efficiently and effectively.
GitHub GraphQL MCP Server
A Model Context Protocol (MCP) server that provides access to GitHub's GraphQL API. This server exposes a single tool that allows executing arbitrary GraphQL queries and mutations against GitHub's API.
Features
- Execute any GraphQL query against GitHub's API
- Comprehensive error handling and reporting
- Detailed documentation with example queries
- Support for variables in GraphQL operations
Prerequisites
- Python 3.10 or higher
- A GitHub Personal Access Token (PAT)
Installation
- Clone this repository
- 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
- Install dependencies:
pip install -r requirements.txt
Usage
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
Configuring with Claude for 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 file and add your GitHub token.
Example Queries
Get 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"
}
Search 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
}
Get 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"
}
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:
- Check your GitHub token has the correct permissions
- Verify your virtual environment is properly set up and activated
- Ensure your token is correctly set in the environment variables
- If using Claude Desktop, ensure the path to Python is correct (use absolute path to the virtual environment Python)
- Look at the server logs for error messages
- Ensure your GraphQL query is valid for GitHub's schema
- Restart Claude for Desktop after making config changes
Common Errors
spawn python ENOENT
- This error means the Python executable wasn't found
- Solution: Use the full path to your Python executable in the virtual environment (e.g.,
/path/to/your/.venv/bin/python
)
ModuleNotFoundError: No module named 'httpx'
(or other packages)
- The Python environment doesn't have the required dependencies installed
- Solution: Make sure you've activated the virtual environment and run
pip install -r requirements.txt
Error: GitHub token not found in environment variables
- The server couldn't find your GitHub token
- Solution: Make sure you've set the GITHUB_TOKEN environment variable