GitHub MCP Server v3.0

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

Tools: 82 (with Git) | 48 (without Git) | Architecture: Hybrid (Local Git + GitHub API + Admin Controls)

What's New in v3.0

• 22 Administrative Tools: Repository settings, branch protection, webhooks, collaborators, teams
• 4-Tier Safety System: Risk classification (LOW/MEDIUM/HIGH/CRITICAL) with confirmation tokens
• Git-Free File Operations: Clone, pull, download repos via GitHub API (no Git required)
• Smart Git Detection: Auto-detects Git availability, filters tools accordingly
• 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):

delete_repo      - For github_delete_repository
workflow         - For re-running GitHub Actions workflows
security_events  - For dismissing security alerts
admin:repo_hook  - Enhanced webhook management (v3.0)
admin:org        - For team management in organizations (v3.0)

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/Linux

# Or compile manually
go build -o mcp-go-github.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\\mcp-go-github.exe",
      "args": ["--profile", "personal"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_token"
      }
    },
    "github-work": {
      "command": "C:\\path\\to\\mcp-go-github.exe",
      "args": ["--profile", "work"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_work_token"
      }
    }
  }
}

Basic Configuration (Single token)

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

Available Tools (82 Tools)

Git Information (8)

Basic Git Operations (6)

Git Analysis & Management (7)

Advanced Git Operations (7)

Conflict Management (6)

Hybrid Operations (2)

GitHub API (4)

File Operations - Git-Free (4) [NEW v3.0]

Dashboard (7)

Response (3)

Repair (6)

Repository Admin (4) [NEW v3.0]

Branch Protection (3) [NEW v3.0]

Webhooks (5) [NEW v3.0]

Collaborators (8) [NEW v3.0]

Teams (2) [NEW v3.0]

Safety System (v3.0)

4 Risk Levels

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.

See safety.json.example for complete configuration reference.

Git-Free Mode (v3.0)

On systems without Git installed (e.g., Mac without Xcode Command Line Tools), the server:

1. Automatically detects Git absence

2. Filters git_ tools from listing

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

4. Returns friendly error if a Git tool is attempted

The 4 File Operations tools (github_list_repo_contents, github_download_file, github_download_repo, github_pull_repo) allow cloning and updating repositories using only the GitHub API, without Git.

Security

• Prevention of argument injection in Git commands
• Path Traversal defense
• Strict user input validation
• SSRF prevention in webhook URLs (v3.0)
• Cryptographic confirmation tokens for destructive operations (v3.0)
• Audit logging of administrative operations (v3.0)

System Requirements

• Go: 1.25.0 or higher
• Git: Optional (auto-detected, 48 tools work without Git)
• github.com/google/go-github: v81.0.0
• golang.org/x/oauth2: v0.34.0
• GitHub Token: Minimum repo permission

Project Status

• 82 operational MCP tools (48 without Git)
• Hybrid local Git + GitHub API system
• 22 administrative tools with safety layer
• 4 Git-free file tools
• Multi-profile support
• Complete testing with real repository
• Production ready (v3.0)

Changelog: See CHANGELOG.md for complete change history

Contributing

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

License

MIT License - see LICENSE file for details.

Security

For security issues, please see our Security Policy.