Content
# 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](#available-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](https://github.com/geropl/github-mcp-go/releases) page.
```bash
# 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:
```bash
# 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:
```bash
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:
```bash
# 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
```bash
# 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](https://semver.org/). 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](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:
```bash
go test ./...
```
## License
This project is licensed under the MIT License - see the LICENSE file for details.
