# GitHub Project MCP Server
A Model Context Protocol (MCP) server for managing GitHub projects and issues using GitHub's GraphQL API.
## Features
- List, create, update, and delete (close) GitHub issues
- List GitHub projects (ProjectsV2)
- Get project items
- Full GraphQL API integration for efficient data fetching
- Easy-to-use CLI with `gps` command
## Installation
### From PyPI (Recommended)
```bash
pip install github-project-mcp
```
### From Source
```bash
git clone <your-repo-url>
cd github-project-mcp
pip install .
```
### For Development
```bash
pip install -e .
```
### From Wheel
```bash
# Install Python `build`
pip install build
# Build the wheel
python -m build
# Install the wheel
pip install dist/github_project_mcp-0.1.0-py3-none-any.whl
```
## Quick Start
1. **Configure your GitHub token:**
```bash
gps config --token YOUR_GITHUB_TOKEN
```
2. **Test the connection:**
```bash
gps test
```
3. **Start the server:**
```bash
gps start
```
## CLI Commands
The `gps` command provides a comprehensive interface for managing the MCP server:
### Server Management
```bash
# Start the server
gps start
# Start with specific token
gps start --token YOUR_TOKEN
# Start as daemon (background process)
gps start --daemon
# Stop the server
Press Ctrl + C
# Check server status
gps status
```
### Configuration
```bash
# Configure GitHub token
gps config --token YOUR_TOKEN
# Show current configuration
gps config --show
# Clear configuration
gps config --clear
```
### Utilities
```bash
# Test GitHub API connection
gps test
# List available MCP tools
gps tools
```
## Integration with AI Coding Assistants
### Claude Desktop
Claude Desktop supports MCP servers natively. Configure it by editing the Claude Desktop configuration:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
Add the following configuration:
```json
{
"mcpServers": {
"github-project": {
"command": "gps",
"args": ["start"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
}
}
```
Or if you've configured the token with `gps config`:
```json
{
"mcpServers": {
"github-project": {
"command": "gps",
"args": ["start"]
}
}
}
```
After adding the configuration, restart Claude Desktop. You'll see the GitHub tools available in the tools menu.
### Cursor.ai
Cursor doesn't natively support MCP yet, but you can use the server as a local API:
1. Start the server as a daemon:
```bash
gps start --daemon
```
2. Create a wrapper script `cursor-github-helper.py`:
```python
import subprocess
import json
def query_github(command, params):
# Use the MCP server via subprocess
result = subprocess.run(
["gps", "query", "--json", json.dumps({"tool": command, "params": params})],
capture_output=True,
text=True
)
return json.loads(result.stdout)
```
3. Reference this in your Cursor rules or documentation for the AI to use.
### Windsurf (Codeium)
Windsurf supports custom tools through its API integration:
1. Install the package globally:
```bash
pip install github-project-mcp
```
2. Add to Windsurf's `~/.windsurf/config.json`:
```json
{
"customTools": {
"github": {
"command": "gps",
"args": ["start"],
"description": "GitHub project and issue management"
}
}
}
```
3. In Windsurf chat, you can now reference GitHub operations:
```
@github list issues in owner/repo
@github create issue "Bug: Application crashes"
```
### Visual Studio Code
For VS Code, you can integrate the MCP server through extensions or terminal commands:
#### Option 1: VS Code Tasks
Add to `.vscode/tasks.json`:
```json
{
"version": "2.0.0",
"tasks": [
{
"label": "Start GitHub MCP Server",
"type": "shell",
"command": "gps start --daemon",
"problemMatcher": [],
"group": "build"
},
{
"label": "List GitHub Issues",
"type": "shell",
"command": "gps",
"args": ["query", "list_issues", "${input:owner}", "${input:repo}"],
"problemMatcher": []
}
],
"inputs": [
{
"id": "owner",
"type": "promptString",
"description": "Repository owner"
},
{
"id": "repo",
"type": "promptString",
"description": "Repository name"
}
]
}
```
#### Option 2: VS Code Extension (Continue.dev)
If using Continue.dev extension for AI assistance:
1. Install Continue.dev extension
2. Add to `~/.continue/config.json`:
```json
{
"tools": [
{
"name": "github",
"command": "gps",
"args": ["start"],
"description": "GitHub project management"
}
]
}
```
#### Option 3: GitHub Copilot Chat
While GitHub Copilot doesn't directly support MCP, you can create command shortcuts:
1. Create a `.github/copilot-instructions.md` file in your project:
```markdown
You have access to a GitHub MCP server. To use it:
- Start server: Run `gps start` in terminal
- List issues: Run `gps query list_issues OWNER REPO`
- Create issue: Run `gps query create_issue OWNER REPO "TITLE" "BODY"`
```
2. Copilot will recognize these commands and can help you use them.
### General Integration Pattern
For any IDE or assistant that doesn't natively support MCP, you can:
1. **Install the package**:
```bash
pip install github-project-mcp
```
2. **Start as a daemon**:
```bash
gps start --daemon
```
3. **Use the CLI programmatically**:
```bash
# List issues
gps query list_issues octocat hello-world
# Create an issue
gps query create_issue octocat hello-world "Bug Report" "Description here"
# Update an issue
gps query update_issue ISSUE_ID --state CLOSED
```
4. **Or use it in Python scripts**:
```python
from github_project_mcp import GitHubGraphQLClient
import os
client = GitHubGraphQLClient(os.getenv("GITHUB_TOKEN"))
issues = await client.list_issues("octocat", "hello-world")
```
## Available Tools
### Issue Management
- **list_issues**: List issues in a repository
- Parameters: `owner`, `repo`, `state` (OPEN/CLOSED)
- **create_issue**: Create a new issue
- Parameters: `owner`, `repo`, `title`, `body`, `labels`, `assignees`
- **update_issue**: Update an existing issue
- Parameters: `issue_id`, `title`, `body`, `state`, `labels`, `assignees`
- **delete_issue**: Close an issue (GitHub doesn't support deletion)
- Parameters: `issue_id`
### Project Management
- **list_projects**: List projects in a repository
- Parameters: `owner`, `repo`
- **get_project_items**: Get items in a project
- Parameters: `project_id`
### Utilities
- **get_repo_id**: Get repository ID for GraphQL mutations
- Parameters: `owner`, `repo`
## Example Usage
### List Open Issues
```json
{
"tool": "list_issues",
"arguments": {
"owner": "octocat",
"repo": "hello-world",
"state": "OPEN"
}
}
```
### Create New Issue
```json
{
"tool": "create_issue",
"arguments": {
"owner": "octocat",
"repo": "hello-world",
"title": "Bug: Application crashes on startup",
"body": "The application crashes when trying to start with the --debug flag"
}
}
```
### Update Issue
```json
{
"tool": "update_issue",
"arguments": {
"issue_id": "I_kwDOBFQLEs5XB1234",
"state": "CLOSED",
"body": "Fixed in PR #123"
}
}
```
## GraphQL API Benefits
This server uses GitHub's GraphQL API v4 instead of REST API v3, providing:
- **Efficient data fetching**: Request only the fields you need
- **Fewer API calls**: Get related data in a single request
- **Better performance**: Reduced network overhead
- **Type safety**: Strongly typed schema
- **Real-time capabilities**: Support for subscriptions (future enhancement)
## Requirements
- Python 3.10+
- GitHub Personal Access Token with appropriate permissions
- Dependencies listed in `requirements.txt`
## License
MIT
## Publishing to PyPI
### Prerequisites
1. **Install build tools**:
```bash
pip install build twine
```
2. **Create PyPI account**:
- Register at https://pypi.org
- Generate API token in account settings
- Optionally, create TestPyPI account at https://test.pypi.org
### Publishing Steps
1. **Update version** in `setup.py` or `pyproject.toml`
2. **Build the package**:
```bash
python -m build
```
3. **Upload to TestPyPI** (optional, for testing):
```bash
twine upload --repository testpypi dist/*
```
- Username: `__token__`
- Password: Your TestPyPI API token
4. **Upload to PyPI**:
```bash
twine upload dist/*
```
- Username: `__token__`
- Password: Your PyPI API token
5. **Verify installation**:
```bash
pip install github-project-mcp
```
### Notes
- Clean the `dist/` directory between builds: `rm -rf dist/`
- Use semantic versioning (e.g., 0.1.0, 0.1.1, 1.0.0)
- Ensure all tests pass before publishing
- Consider using GitHub Actions for automated publishing
## Contributing
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Raw data
{
"_id": null,
"home_page": "https://github.com/jaqarx/github-project-mcp",
"name": "github-project-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "github, mcp, graphql, api, project-management",
"author": "Enrica Tan",
"author_email": "Enrica Tan <tanenrica@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/5c/50/7ad361138290d060203a65f0da502d9bb64493473cb74fe1bef77caba84e/github_project_mcp-0.1.0.tar.gz",
"platform": null,
"description": "# GitHub Project MCP Server\n\nA Model Context Protocol (MCP) server for managing GitHub projects and issues using GitHub's GraphQL API.\n\n## Features\n\n- List, create, update, and delete (close) GitHub issues\n- List GitHub projects (ProjectsV2)\n- Get project items\n- Full GraphQL API integration for efficient data fetching\n- Easy-to-use CLI with `gps` command\n\n## Installation\n\n### From PyPI (Recommended)\n\n```bash\npip install github-project-mcp\n```\n\n### From Source\n\n```bash\ngit clone <your-repo-url>\ncd github-project-mcp\npip install .\n```\n\n### For Development\n\n```bash\npip install -e .\n```\n\n### From Wheel\n\n```bash\n# Install Python `build`\npip install build\n\n# Build the wheel\npython -m build\n\n# Install the wheel\npip install dist/github_project_mcp-0.1.0-py3-none-any.whl\n```\n\n## Quick Start\n\n1. **Configure your GitHub token:**\n```bash\ngps config --token YOUR_GITHUB_TOKEN\n```\n\n2. **Test the connection:**\n```bash\ngps test\n```\n\n3. **Start the server:**\n```bash\ngps start\n```\n\n## CLI Commands\n\nThe `gps` command provides a comprehensive interface for managing the MCP server:\n\n### Server Management\n\n```bash\n# Start the server\ngps start\n\n# Start with specific token\ngps start --token YOUR_TOKEN\n\n# Start as daemon (background process)\ngps start --daemon\n\n# Stop the server\nPress Ctrl + C\n\n# Check server status\ngps status\n```\n\n### Configuration\n\n```bash\n# Configure GitHub token\ngps config --token YOUR_TOKEN\n\n# Show current configuration\ngps config --show\n\n# Clear configuration\ngps config --clear\n```\n\n### Utilities\n\n```bash\n# Test GitHub API connection\ngps test\n\n# List available MCP tools\ngps tools\n```\n\n## Integration with AI Coding Assistants\n\n### Claude Desktop\n\nClaude Desktop supports MCP servers natively. Configure it by editing the Claude Desktop configuration:\n\n**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` \n**Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json` \n**Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nAdd the following configuration:\n\n```json\n{\n \"mcpServers\": {\n \"github-project\": {\n \"command\": \"gps\",\n \"args\": [\"start\"],\n \"env\": {\n \"GITHUB_TOKEN\": \"your_github_token_here\"\n }\n }\n }\n}\n```\n\nOr if you've configured the token with `gps config`:\n\n```json\n{\n \"mcpServers\": {\n \"github-project\": {\n \"command\": \"gps\",\n \"args\": [\"start\"]\n }\n }\n}\n```\n\nAfter adding the configuration, restart Claude Desktop. You'll see the GitHub tools available in the tools menu.\n\n### Cursor.ai\n\nCursor doesn't natively support MCP yet, but you can use the server as a local API:\n\n1. Start the server as a daemon:\n```bash\ngps start --daemon\n```\n\n2. Create a wrapper script `cursor-github-helper.py`:\n```python\nimport subprocess\nimport json\n\ndef query_github(command, params):\n # Use the MCP server via subprocess\n result = subprocess.run(\n [\"gps\", \"query\", \"--json\", json.dumps({\"tool\": command, \"params\": params})],\n capture_output=True,\n text=True\n )\n return json.loads(result.stdout)\n```\n\n3. Reference this in your Cursor rules or documentation for the AI to use.\n\n### Windsurf (Codeium)\n\nWindsurf supports custom tools through its API integration:\n\n1. Install the package globally:\n```bash\npip install github-project-mcp\n```\n\n2. Add to Windsurf's `~/.windsurf/config.json`:\n```json\n{\n \"customTools\": {\n \"github\": {\n \"command\": \"gps\",\n \"args\": [\"start\"],\n \"description\": \"GitHub project and issue management\"\n }\n }\n}\n```\n\n3. In Windsurf chat, you can now reference GitHub operations:\n```\n@github list issues in owner/repo\n@github create issue \"Bug: Application crashes\"\n```\n\n### Visual Studio Code\n\nFor VS Code, you can integrate the MCP server through extensions or terminal commands:\n\n#### Option 1: VS Code Tasks\n\nAdd to `.vscode/tasks.json`:\n```json\n{\n \"version\": \"2.0.0\",\n \"tasks\": [\n {\n \"label\": \"Start GitHub MCP Server\",\n \"type\": \"shell\",\n \"command\": \"gps start --daemon\",\n \"problemMatcher\": [],\n \"group\": \"build\"\n },\n {\n \"label\": \"List GitHub Issues\",\n \"type\": \"shell\",\n \"command\": \"gps\",\n \"args\": [\"query\", \"list_issues\", \"${input:owner}\", \"${input:repo}\"],\n \"problemMatcher\": []\n }\n ],\n \"inputs\": [\n {\n \"id\": \"owner\",\n \"type\": \"promptString\",\n \"description\": \"Repository owner\"\n },\n {\n \"id\": \"repo\",\n \"type\": \"promptString\",\n \"description\": \"Repository name\"\n }\n ]\n}\n```\n\n#### Option 2: VS Code Extension (Continue.dev)\n\nIf using Continue.dev extension for AI assistance:\n\n1. Install Continue.dev extension\n2. Add to `~/.continue/config.json`:\n```json\n{\n \"tools\": [\n {\n \"name\": \"github\",\n \"command\": \"gps\",\n \"args\": [\"start\"],\n \"description\": \"GitHub project management\"\n }\n ]\n}\n```\n\n#### Option 3: GitHub Copilot Chat\n\nWhile GitHub Copilot doesn't directly support MCP, you can create command shortcuts:\n\n1. Create a `.github/copilot-instructions.md` file in your project:\n```markdown\nYou have access to a GitHub MCP server. To use it:\n- Start server: Run `gps start` in terminal\n- List issues: Run `gps query list_issues OWNER REPO`\n- Create issue: Run `gps query create_issue OWNER REPO \"TITLE\" \"BODY\"`\n```\n\n2. Copilot will recognize these commands and can help you use them.\n\n### General Integration Pattern\n\nFor any IDE or assistant that doesn't natively support MCP, you can:\n\n1. **Install the package**:\n```bash\npip install github-project-mcp\n```\n\n2. **Start as a daemon**:\n```bash\ngps start --daemon\n```\n\n3. **Use the CLI programmatically**:\n```bash\n# List issues\ngps query list_issues octocat hello-world\n\n# Create an issue\ngps query create_issue octocat hello-world \"Bug Report\" \"Description here\"\n\n# Update an issue\ngps query update_issue ISSUE_ID --state CLOSED\n```\n\n4. **Or use it in Python scripts**:\n```python\nfrom github_project_mcp import GitHubGraphQLClient\nimport os\n\nclient = GitHubGraphQLClient(os.getenv(\"GITHUB_TOKEN\"))\nissues = await client.list_issues(\"octocat\", \"hello-world\")\n```\n\n## Available Tools\n\n### Issue Management\n\n- **list_issues**: List issues in a repository\n - Parameters: `owner`, `repo`, `state` (OPEN/CLOSED)\n \n- **create_issue**: Create a new issue\n - Parameters: `owner`, `repo`, `title`, `body`, `labels`, `assignees`\n \n- **update_issue**: Update an existing issue\n - Parameters: `issue_id`, `title`, `body`, `state`, `labels`, `assignees`\n \n- **delete_issue**: Close an issue (GitHub doesn't support deletion)\n - Parameters: `issue_id`\n\n### Project Management\n\n- **list_projects**: List projects in a repository\n - Parameters: `owner`, `repo`\n \n- **get_project_items**: Get items in a project\n - Parameters: `project_id`\n\n### Utilities\n\n- **get_repo_id**: Get repository ID for GraphQL mutations\n - Parameters: `owner`, `repo`\n\n## Example Usage\n\n### List Open Issues\n```json\n{\n \"tool\": \"list_issues\",\n \"arguments\": {\n \"owner\": \"octocat\",\n \"repo\": \"hello-world\",\n \"state\": \"OPEN\"\n }\n}\n```\n\n### Create New Issue\n```json\n{\n \"tool\": \"create_issue\",\n \"arguments\": {\n \"owner\": \"octocat\",\n \"repo\": \"hello-world\",\n \"title\": \"Bug: Application crashes on startup\",\n \"body\": \"The application crashes when trying to start with the --debug flag\"\n }\n}\n```\n\n### Update Issue\n```json\n{\n \"tool\": \"update_issue\",\n \"arguments\": {\n \"issue_id\": \"I_kwDOBFQLEs5XB1234\",\n \"state\": \"CLOSED\",\n \"body\": \"Fixed in PR #123\"\n }\n}\n```\n\n## GraphQL API Benefits\n\nThis server uses GitHub's GraphQL API v4 instead of REST API v3, providing:\n\n- **Efficient data fetching**: Request only the fields you need\n- **Fewer API calls**: Get related data in a single request\n- **Better performance**: Reduced network overhead\n- **Type safety**: Strongly typed schema\n- **Real-time capabilities**: Support for subscriptions (future enhancement)\n\n## Requirements\n\n- Python 3.10+\n- GitHub Personal Access Token with appropriate permissions\n- Dependencies listed in `requirements.txt`\n\n## License\n\nMIT\n\n## Publishing to PyPI\n\n### Prerequisites\n\n1. **Install build tools**:\n```bash\npip install build twine\n```\n\n2. **Create PyPI account**:\n - Register at https://pypi.org\n - Generate API token in account settings\n - Optionally, create TestPyPI account at https://test.pypi.org\n\n### Publishing Steps\n\n1. **Update version** in `setup.py` or `pyproject.toml`\n\n2. **Build the package**:\n```bash\npython -m build\n```\n\n3. **Upload to TestPyPI** (optional, for testing):\n```bash\ntwine upload --repository testpypi dist/*\n```\n - Username: `__token__`\n - Password: Your TestPyPI API token\n\n4. **Upload to PyPI**:\n```bash\ntwine upload dist/*\n```\n - Username: `__token__`\n - Password: Your PyPI API token\n\n5. **Verify installation**:\n```bash\npip install github-project-mcp\n```\n\n### Notes\n\n- Clean the `dist/` directory between builds: `rm -rf dist/`\n- Use semantic versioning (e.g., 0.1.0, 0.1.1, 1.0.0)\n- Ensure all tests pass before publishing\n- Consider using GitHub Actions for automated publishing\n\n## Contributing\n\nPull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A Model Context Protocol server for managing GitHub projects and issues via GraphQL",
"version": "0.1.0",
"project_urls": {
"Documentation": "https://github.com/yourusername/github-project-mcp#readme",
"Homepage": "https://github.com/yourusername/github-project-mcp",
"Issues": "https://github.com/yourusername/github-project-mcp/issues",
"Repository": "https://github.com/yourusername/github-project-mcp"
},
"split_keywords": [
"github",
" mcp",
" graphql",
" api",
" project-management"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "83cde121d68bed0a348fa1face0b15ef0ed2b58ea7286dae3a2b2d45999173c0",
"md5": "f4a37b18ee77e284b8c297339d2de101",
"sha256": "90f6fd5b3666ff214c1c688ac1dceda6657760995a5dad1c28281323e87e3c47"
},
"downloads": -1,
"filename": "github_project_mcp-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4a37b18ee77e284b8c297339d2de101",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 13619,
"upload_time": "2025-08-06T04:41:06",
"upload_time_iso_8601": "2025-08-06T04:41:06.173238Z",
"url": "https://files.pythonhosted.org/packages/83/cd/e121d68bed0a348fa1face0b15ef0ed2b58ea7286dae3a2b2d45999173c0/github_project_mcp-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "5c507ad361138290d060203a65f0da502d9bb64493473cb74fe1bef77caba84e",
"md5": "916b9968e5fc0a17f1ca28c066a91caa",
"sha256": "8dbf501afda3c83c6ddb85faf1e524c17e0ef035d7da4d82551c6e504972b058"
},
"downloads": -1,
"filename": "github_project_mcp-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "916b9968e5fc0a17f1ca28c066a91caa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 16386,
"upload_time": "2025-08-06T04:41:07",
"upload_time_iso_8601": "2025-08-06T04:41:07.899456Z",
"url": "https://files.pythonhosted.org/packages/5c/50/7ad361138290d060203a65f0da502d9bb64493473cb74fe1bef77caba84e/github_project_mcp-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-06 04:41:07",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jaqarx",
"github_project": "github-project-mcp",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "mcp",
"specs": [
[
">=",
"0.9.0"
]
]
},
{
"name": "httpx",
"specs": [
[
">=",
"0.27.0"
]
]
},
{
"name": "python-dotenv",
"specs": [
[
">=",
"1.0.0"
]
]
},
{
"name": "click",
"specs": [
[
">=",
"8.1.0"
]
]
},
{
"name": "rich",
"specs": [
[
">=",
"13.0.0"
]
]
}
],
"lcname": "github-project-mcp"
}
JSON
