GitHub GraphQL MCP Server

1# GitHub GraphQL MCP Server
2 
3[![QuentinCody/github-graphql-mcp-server context](https://badge.forgithub.com/QuentinCody/github-graphql-mcp-server?accept=text%2Fhtml&maxTokens=50000&ext=py)](https://uithub.com/QuentinCody/github-graphql-mcp-server?accept=text%2Fhtml&maxTokens=50000&ext=py)
4 
5A 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.
6 
7## Features
8 
9- Execute any GraphQL query against GitHub's API
10- Comprehensive error handling and reporting
11- Detailed documentation with example queries
12- Support for variables in GraphQL operations
13 
14## Prerequisites
15 
16- Python 3.10 or higher
17- A GitHub Personal Access Token (PAT)
18 
19## Installation
20 
211. Clone this repository
222. Set up a virtual environment (recommended):
23   ```bash
24   # On macOS/Linux
25   python3 -m venv .venv
26   source .venv/bin/activate
27   
28   # On Windows
29   python -m venv .venv
30   .venv\Scripts\activate
31   ```
323. Install dependencies:
33   ```bash
34   pip install -r requirements.txt
35   ```
36 
37## Usage
38 
39### Running the Server
40 
41```bash
42# If using a virtual environment, make sure it's activated
43source .venv/bin/activate  # On Windows: .venv\Scripts\activate
44 
45# Run the server with your GitHub token
46GITHUB_TOKEN=your_github_token_here python github_graphql_mcp_server.py
47```
48 
49### Configuring with Claude for Desktop
50 
51Add the following to your Claude Desktop configuration file:
52 
53```json
54{
55  "github-graphql": {
56    "command": "/absolute/path/to/your/.venv/bin/python",
57    "args": [
58        "/absolute/path/to/github_graphql_mcp_server.py"
59    ],
60    "options": {
61        "cwd": "/absolute/path/to/repository"
62    },
63    "env": {
64        "GITHUB_TOKEN": "your_github_token_here"
65    }
66  }
67}
68```
69 
70Replace `/absolute/path/to/` with the actual path to your server file and add your GitHub token.
71 
72### Example Queries
73 
74#### Get Repository Information
75 
76```graphql
77query GetRepo($owner: String!, $name: String!) {
78  repository(owner: $owner, name: $name) {
79    name
80    description
81    stargazerCount
82    url
83    createdAt
84    owner {
85      login
86      avatarUrl
87    }
88  }
89}
90```
91 
92Variables:
93```json
94{
95  "owner": "octocat",
96  "name": "Hello-World"
97}
98```
99 
100#### Search Repositories
101 
102```graphql
103query SearchRepos($query: String!, $first: Int!) {
104  search(query: $query, type: REPOSITORY, first: $first) {
105    repositoryCount
106    edges {
107      node {
108        ... on Repository {
109          name
110          owner { login }
111          description
112          stargazerCount
113          url
114        }
115      }
116    }
117  }
118}
119```
120 
121Variables:
122```json
123{
124  "query": "language:python stars:1000",
125  "first": 5
126}
127```
128 
129#### Get User Information
130 
131```graphql
132query GetUserInfo($login: String!) {
133  user(login: $login) {
134    name
135    login
136    bio
137    avatarUrl
138    followers {
139      totalCount
140    }
141    repositories(first: 5, orderBy: {field: STARGAZERS, direction: DESC}) {
142      nodes {
143        name
144        description
145        stargazerCount
146      }
147    }
148  }
149}
150```
151 
152Variables:
153```json
154{
155  "login": "octocat"
156}
157```
158 
159## GitHub API Rate Limits
160 
161Be aware of GitHub's API rate limits:
162- Authenticated requests: 5,000 requests per hour
163- Unauthenticated requests: 60 requests per hour
164 
165## Troubleshooting
166 
167If you encounter issues:
168 
1691. Check your GitHub token has the correct permissions
1702. Verify your virtual environment is properly set up and activated
1713. Ensure your token is correctly set in the environment variables
1724. If using Claude Desktop, ensure the path to Python is correct (use absolute path to the virtual environment Python)
1735. Look at the server logs for error messages
1746. Ensure your GraphQL query is valid for GitHub's schema
1757. Restart Claude for Desktop after making config changes
176 
177### Common Errors
178 
179**`spawn python ENOENT`**
180- This error means the Python executable wasn't found
181- Solution: Use the full path to your Python executable in the virtual environment (e.g., `/path/to/your/.venv/bin/python`)
182 
183**`ModuleNotFoundError: No module named 'httpx'` (or other packages)**
184- The Python environment doesn't have the required dependencies installed
185- Solution: Make sure you've activated the virtual environment and run `pip install -r requirements.txt`
186 
187**`Error: GitHub token not found in environment variables`**
188- The server couldn't find your GitHub token
189 
190- Solution: Make sure you've set the GITHUB_TOKEN environment variable
191 
192## License
193 
194[MIT](LICENSE)
195=======
196 
197