GitHub MCP Server v4.0

Go-based MCP server that connects GitHub to Claude Desktop, enabling direct repository operations from Claude's interface.

Tools: 26 consolidated tools (85 operations) | Architecture: Hybrid (Local Git + GitHub API + Admin Controls)

What's New in v4.0

• Consolidated Tool Design: 85 operations across just 26 tools — prevents AI confusion from tool-count limits
• Operation Parameter Pattern: Each tool accepts an `operation` parameter to select the specific action
• `--toolsets` Flag: Start the server exposing only selected tool groups (`git`, `github`, `admin`, `files`)
• Real Auto-Backup: Writes a JSON backup before HIGH/CRITICAL operations when `enable_auto_backup: true`
• 4-Tier Safety System: Risk classification (LOW/MEDIUM/HIGH/CRITICAL) with confirmation tokens
• 22 Administrative Operations: Repository settings, branch protection, webhooks, collaborators, teams
• Audit Logging: JSON-based operation tracking with automatic rotation

Token Permissions Required

Minimum Required

repo        - Full control of private repositories (essential)

Optional (for full functionality)

security_events  - For dismissing security alerts
workflow         - For re-running GitHub Actions workflows
admin:repo_hook  - Enhanced webhook management
admin:org        - For team management in organizations

Generate Token

1. Go to: GitHub Settings > Personal Access Tokens

2. Click "Generate new token (classic)"

3. Select the required scopes

4. Copy the generated token

Installation

# Install dependencies
go mod tidy

# Compile (using included script)
.\compile.bat          # Windows
./build-mac.bat        # macOS cross-compile

# Or compile manually
go build -o github-mcp-server-v4.exe ./cmd/github-mcp-server/

Testing

# Run all tests
go test ./...

# Run tests with verbose output
go test ./... -v

# Run tests for a specific package
go test ./pkg/git/ -v
go test ./pkg/safety/ -v

Claude Desktop Configuration

Multi-profile (Recommended)

{
  "mcpServers": {
    "github-personal": {
      "command": "C:\\path\\to\\github-mcp-server-v4.exe",
      "args": ["--profile", "personal"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_token"
      }
    },
    "github-work": {
      "command": "C:\\path\\to\\github-mcp-server-v4.exe",
      "args": ["--profile", "work"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_work_token"
      }
    }
  }
}

Basic Configuration (Single token)

{
  "mcpServers": {
    "github-mcp": {
      "command": "C:\\path\\to\\github-mcp-server-v4.exe",
      "args": [],
      "env": {
        "GITHUB_TOKEN": "your_token_here"
      }
    }
  }
}

Toolset Filtering (Optional)

Expose only specific tool groups to reduce attack surface:

{
  "args": ["--toolsets", "git,github"]
}

Available groups: `git` (14 tools), `github` (4 tools), `admin` (4 tools), `files` (4 tools). Default is `all`.

Available Tools (26)

Tools use an `operation` parameter to expose multiple operations under one name. This reduces the tool count from 85 to 26, preventing AI model confusion.

Git Info (2 tools)

Git Basic (3 tools)

Git Advanced (9 tools)

Hybrid (3 tools)

GitHub API (1 tool)

Dashboard (1 tool)

Response (1 tool)

Repair (1 tool)

Admin (4 tools)

File Operations (1 tool)

Safety System

4-Tier Risk Classification

Safety uses composite keys `tool:operation` (e.g., `github_webhooks:delete`) for risk classification.

Safety Modes

Safety Configuration

Create `safety.json` next to the executable (optional):

{
  "mode": "moderate",
  "enable_audit_log": true,
  "require_confirmation_above": 3,
  "audit_log_path": "./mcp-admin-audit.log",
  "audit_log_max_size_mb": 10,
  "audit_log_max_backups": 5
}

If `safety.json` doesn't exist, defaults to moderate mode with audit logging enabled.

Git-Free Mode

On systems without Git installed, the server:

1. Automatically detects Git absence

2. Filters `git_*` tools from the listing

3. Keeps all API, admin, dashboard, and file operation tools operational

4. Returns a friendly error if a Git tool is attempted

The `github_files` tool (`list`, `download`, `download_repo`, `pull_repo`) allows cloning and updating repositories using only the GitHub API, without Git.

Security

• Command injection prevention in all Git operations
• Path traversal defense
• SSRF prevention in webhook URLs
• Cryptographic confirmation tokens for destructive operations
• Audit logging of all administrative operations

For vulnerability reports, see our Security Policy.

System Requirements

• Go: 1.26.6 or higher
• Git: Optional (auto-detected; file/API tools work without it)
• `github.com/google/go-github` v88.0.0
• `golang.org/x/oauth2` v0.36.0
• GitHub Token: Minimum `repo` permission

Project Status

• 26 consolidated tools exposing 85 operations
• Hybrid local Git + GitHub API system
• 4-tier safety system with confirmation tokens and auto-backup
• Multi-profile support
• Complete test suite
• Production ready (v4.0)

Changelog: See CHANGELOG.md for complete change history.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

MIT License — see LICENSE for details.