# GitHub MCP Server
A Model Context Protocol (MCP) server that enables LLMs to interact with GitHub repositories, issues, pull requests, workflows, and more.
## Features
### Repository Management
- **search_repositories** - Search repos by query, language, stars
- **get_repository** - Get detailed repo information
- **list_repository_files** - Browse directory contents
- **get_file_contents** - Read file content
### Issue Tracking
- **list_issues** - List/filter issues by state, labels, assignee
- **get_issue** - Get issue details with comments
- **create_issue** - Create new issues
- **update_issue** - Update existing issues
- **add_issue_comment** - Comment on issues
### Pull Requests
- **list_pull_requests** - List PRs with filters
- **get_pull_request** - Get PR details with diff stats
- **create_pull_request** - Create new PRs
- **list_pr_files** - List changed files
- **merge_pull_request** - Merge PRs (merge/squash/rebase)
### Branches & Commits
- **list_branches** - List branches with protection status
- **get_commits** - Get commit history
- **compare_commits** - Compare branches/tags/commits
### GitHub Actions
- **list_workflows** - List workflow files
- **get_workflow_runs** - Get recent workflow runs
- **trigger_workflow** - Dispatch workflow runs
### Code Search
- **search_code** - Search code across repositories
### Users & Organizations
- **get_user** - Get user/org profile
- **list_user_repos** - List user's repositories
## Installation
```bash
# Clone the repository
git clone https://github.com/yourusername/github-mcp-server.git
cd github-mcp-server
# Create virtual environment
python -m venv venv
source venv/bin/activate # Linux/Mac
# or
venv\Scripts\activate # Windows
# Install dependencies
pip install -r requirements.txt
```
## Configuration
### GitHub Token
Create a Personal Access Token at https://github.com/settings/tokens with these scopes:
- `repo` - Full control of private repositories
- `read:org` - Read organization membership
- `workflow` - Update GitHub Action workflows
Set the token as an environment variable:
```bash
# Linux/Mac
export GITHUB_TOKEN=ghp_your_token_here
# Windows (PowerShell)
$env:GITHUB_TOKEN = "ghp_your_token_here"
# Windows (CMD)
set GITHUB_TOKEN=ghp_your_token_here
```
## Usage
### Running the Server
```bash
# Direct execution
python github_mcp_server.py
# With MCP Inspector (development)
uv run mcp dev github_mcp_server.py
# With MCP CLI
uv run mcp run github_mcp_server.py
```
### Claude Desktop Integration
Add to your Claude Desktop config (`~/.config/claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"github": {
"command": "python",
"args": ["/path/to/github_mcp_server.py"],
"env": {
"GITHUB_TOKEN": "ghp_your_token_here"
}
}
}
}
```
## Tool Examples
### Search Repositories
```
search_repositories("kubernetes helm language:go stars:>1000")
```
### Get Repository Info
```
get_repository("microsoft", "vscode")
```
### List Issues
```
list_issues("owner", "repo", state="open", labels="bug,help wanted")
```
### Create Issue
```
create_issue("owner", "repo", "Bug: Login fails", body="Steps to reproduce...", labels=["bug"])
```
### List Pull Requests
```
list_pull_requests("owner", "repo", state="open")
```
### Create Pull Request
```
create_pull_request("owner", "repo", "Add feature X", "feature-branch", "main")
```
### Search Code
```
search_code("import tensorflow language:python")
```
### Get Workflow Runs
```
get_workflow_runs("owner", "repo", branch="main", status="completed")
```
## Response Formats
All tools support two response formats:
- **markdown** (default) - Human-readable formatted output
- **json** - Structured data for programmatic use
```
get_repository("owner", "repo", format="json")
```
## Error Handling
The server provides actionable error messages:
- **Rate Limiting**: Indicates when limits reset
- **Not Found**: Suggests verifying resource exists
- **Authentication**: Prompts to check token validity
- **Validation**: Lists specific field errors
## Architecture
```
github_mcp_server.py
├── Configuration (API_BASE_URL, CHARACTER_LIMIT)
├── Enums (ResponseFormat, IssueState, PRMergeMethod)
├── Pydantic Models (input validation)
├── API Client Helpers (github_request, truncate_content)
├── Repository Tools (search, get, list files, read)
├── Issue Tools (list, get, create, update, comment)
├── Pull Request Tools (list, get, create, merge)
├── Branch & Commit Tools (list, history, compare)
├── Actions Tools (workflows, runs, trigger)
├── Code Search Tool
├── User Tools (profile, repos)
└── Server Entry Point
```
## Development
### Testing Syntax
```bash
python -m py_compile github_mcp_server.py
```
### Running in Development
```bash
# With MCP Inspector
uv run mcp dev github_mcp_server.py
```
## License
MIT License
## Author
Hansen Nkefor
