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

# 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:

# 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

# 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):

{
  "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

python -m py_compile github_mcp_server.py

Running in Development

# With MCP Inspector
uv run mcp dev github_mcp_server.py

License

MIT License

Author

Hansen Nkefor