github-graphql-mcp-server
If you are the rightful owner of github-graphql-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcpreview.com.
A Model Context Protocol (MCP) server that provides access to GitHub's GraphQL API.
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