GitHub MCP Server

A Model Context Protocol (MCP) server for GitHub, implemented in Go. This server allows LLMs to interact with GitHub repositories, issues, pull requests, and more through a standardized interface.

Features

• Comprehensive GitHub API Access: See Tools below
• Setup Command: Easy automatic setup for AI assistants
  • --auto-approve allows to pre-fill the auto-approval checkbox
  • --write-access enables write access for remote operations
  • Copies the binary into a stable location
  • Updates the tool MCP server config (cline and claude-desktop are supported)
• Security Controls:
  • Write access is disabled by default for safety
  • Fine-grained auto-approval options

Planned Features

• "get_diff"
  • diff between two commits
  • ? Should this be in the output of compare_commits?

Installation

Prerequisites

• GitHub Personal Access Token with appropriate permissions

Using Pre-built Binaries

You can download pre-built binaries for your platform from the GitHub Releases page.

# Download the latest release - for "linux_amd64" in this case
RELEASE="$(curl -s https://api.github.com/repos/geropl/github-mcp-go/releases/latest)"
DOWNLOAD_URL="$(echo $RELEASE | jq -r '.assets[] | select(.name | contains("linux_amd64")) | .browser_download_url')"
curl -L -o ./github-mcp-go $DOWNLOAD_URL
chmod +x ./github-mcp-go

# Setup the mcp server (can be called in .gitpod.yml, dotfiles repo, etc.)
./github-mcp-go setup --write-access="${GITHUB_MCP_WRITE_ACCESS:-false}" --auto-approve=allow-read-only || true
rm -f ./github-mcp-go

Building from Source

If you prefer to build from source:

# Prerequisites: Go 1.23 or later

# Clone the repository
git clone https://github.com/geropl/github-mcp-go.git
cd github-mcp-go

# Build the server
go build -o github-mcp-go .

Usage

Environment Variables

The server requires a GitHub Personal Access Token to authenticate with the GitHub API:

export GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here

Setup

The server includes a convenient setup command to install and configure the MCP server for use with AI assistants:

# Set up for Cline with auto-approval for read-only tools
./github-mcp-go setup --auto-approve allow-read-only --tool cline

# Set up for Claude Desktop with auto-approval for specific tools
./github-mcp-go setup --auto-approve search_repositories,get_file_contents --tool claude-desktop

# Set up with write access enabled
./github-mcp-go setup --write-access --tool cline

# Show setup help
./github-mcp-go setup --help

Running the Server

# Run the server directly (read-only mode)
./github-mcp-go serve

# Run the server with write access enabled
./github-mcp-go serve --write-access

# Show help
./github-mcp-go --help

Auto-Approval Options

The --auto-approve flag can be used to specify which tools should be auto-approved as a comma-separated list. allow-read-only is a special value to add all read-only tools to the auto-approve list (safe, no state changes).

The --write-access flag enables write access for remote operations. This allows tools that modify remote repositories to be used. By default, write access is disabled for safety.

Available Tools

Repository Tools

• search_repositories: Search for GitHub repositories
• create_repository: Create a new GitHub repository
• fork_repository: Fork a GitHub repository

Pull Request Tools

• create_pull_request: Create a new pull request
• get_pull_request: Get detailed information about a pull request
• get_pull_request_diff: Get the diff of a pull request

File Tools

• get_file_contents: Get the contents of a file or directory
• create_or_update_file: Create or update a file
• push_files: Push multiple files in a single commit

Issue Tools

• create_issue: Create a new issue
• list_issues: List issues with filtering options
• update_issue: Update an existing issue
• add_issue_comment: Add a comment to an issue
• get_issue: Get details of a specific issue
• list_issue_comments: List comments on an issue

Branch Tools

• list_branches: List branches in a repository
• get_branch: Get details about a specific branch
• create_branch: Create a new branch
• merge_branches: Merge one branch into another
• delete_branch: Delete a branch

Commit Tools

• get_commit: Get details of a specific commit
• list_commits: List commits in a repository
• compare_commits: Compare two commits or branches
• get_commit_status: Get the combined status for a specific commit
• create_commit_comment: Add a comment to a specific commit
• list_commit_comments: List comments for a specific commit
• create_commit: Create a new commit directly

Search Tools

• search_code: Search for code across repositories
• search_issues: Search for issues and pull requests
• search_commits: Search for commits across repositories

GitHub Actions Tools

• list_workflows: List all workflows in a repository
• get_workflow: Get detailed information about a specific workflow
• list_workflow_runs: List workflow runs for a repository or specific workflow
• get_workflow_run: Get detailed information about a specific workflow run
• download_workflow_run_logs: Download and process logs for a workflow run
• list_workflow_jobs: List jobs for a workflow run
• get_workflow_job: Get detailed information about a specific job

Releases

The project follows Semantic Versioning. New releases are automatically built and published to GitHub Releases when a new tag is pushed to the repository.

For detailed instructions on creating a new release, see RELEASE.md.

Available Platforms

Pre-built binaries are available for:

• Linux (amd64, arm64)
• macOS (amd64, arm64)
• Windows (amd64)

Development

Testing

The project uses table-driven tests with go-vcr for recording HTTP interactions:

go test ./...

License

This project is licensed under the MIT License - see the LICENSE file for details.