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.