mylxsw/github-mcp

GitHub MCP Server

A Model Context Protocol (MCP) server for GitHub repository operations. This server provides tools to interact with GitHub repositories through the GitHub API.

Features

• File Operations: Write, read, list, and delete files in GitHub repositories
• Branch Management: Create, list, and get information about branches
• Multi-Branch Support: All file operations can target specific branches
• Repository Information: Get detailed information about the repository
• Commit History: Retrieve recent commits
• File Search: Search for files by name or content across branches
• Authentication: Secure token-based authentication

Setup

Prerequisites

• Python 3.13+
• GitHub Personal Access Token
• GitHub repository URL

Installation

1. Install dependencies:

pip install -e .

Environment Variables

Set the following environment variables:

# Required
export GITHUB_REPO_URL="username/repository"  # or full URL like "https://github.com/username/repository"
export GITHUB_API_TOKEN="your_github_token"

# Optional (for authentication)
export GITHUB_MCP_AUTH_TOKEN="your_mcp_auth_token"

GitHub Token Setup

1. Go to GitHub Settings > Developer settings > Personal access tokens > Tokens (classic)
2. Generate a new token with the following scopes:
   • repo (Full control of private repositories)
   • public_repo (Access public repositories)

Usage

Running the Server

python server.py

The server will start on http://0.0.0.0:8000.

Available Tools

File Operations

• write_file: Write content to a file in the repository (supports branch targeting)
• read_file: Read content from a file in the repository (supports branch targeting)
• list_files: List all files in the repository or a specific directory (supports branch targeting)
• delete_file: Delete a file from the repository (supports branch targeting)

Branch Management

• list_branches: List all branches in the repository
• create_branch: Create a new branch from an existing branch
• get_branch_info: Get detailed information about a specific branch

Repository Information

• get_repository_info: Get detailed information about the repository
• get_recent_commits: Get recent commits from the repository
• search_files: Search for files by name or content (supports branch targeting)

Example Usage

# Write a file to a specific branch
write_file(
    filepath="src/main.py",
    content="print('Hello, World!')",
    commit_message="Add main.py file",
    branch="feature/new-feature"
)

# Read a file from a specific branch
content = read_file("src/main.py", branch="feature/new-feature")

# List files in a specific branch
files = list_files("src/", branch="feature/new-feature")

# Create a new branch
create_branch("feature/new-feature", from_branch="main")

# List all branches
branches = list_branches()

# Get branch information
branch_info = get_branch_info("feature/new-feature")

# Search files in a specific branch
results = search_files("main", "src/", branch="feature/new-feature")

API Reference

Tools

write_file

• filepath (str): Path to the file in the repository
• content (str): Content to write to the file
• commit_message (str, optional): Custom commit message
• branch (str, optional): Branch to write to (defaults to repository default branch)

read_file

• filepath (str): Path to the file to read
• branch (str, optional): Branch to read from (defaults to repository default branch)

list_files

• path (str, optional): Directory path to list (empty for root)
• branch (str, optional): Branch to list files from (defaults to repository default branch)

delete_file

• filepath (str): Path to the file to delete
• commit_message (str, optional): Custom commit message
• branch (str, optional): Branch to delete from (defaults to repository default branch)

list_branches

• No parameters

create_branch

• branch_name (str): Name of the new branch to create
• from_branch (str, optional): Branch to create from (defaults to repository default branch)

get_branch_info

• branch_name (str, optional): Name of the branch to get info for (defaults to repository default branch)

search_files

• query (str): Search query for file names or content
• path (str, optional): Directory to search in
• branch (str, optional): Branch to search in (defaults to repository default branch)

Resources

github://repository/info

Returns detailed repository information including name, description, stars, forks, etc.

github://repository/commits

Returns recent commits with author and committer information.

github://repository/branches

Returns information about all branches in the repository.

Error Handling

The server includes comprehensive error handling for:

• Invalid repository URLs
• Missing or invalid API tokens
• File not found errors
• GitHub API rate limits
• Network connectivity issues

Security

• All operations require a valid GitHub API token
• Optional MCP authentication token for additional security
• Repository access is limited to the configured repository
• All file operations are logged for audit purposes