Configuration

Claude Desktop Configuration

The GitHub MCP Server connects to Claude Desktop via the MCP (Model Context Protocol). You’ll configure this in Claude Desktop’s settings file.

Configuration File Location

Windows

%APPDATA%\Claude\claude_desktop_config.json

Typically: C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

macOS

~/Library/Application Support/Claude/claude_desktop_config.json

Linux

~/.config/Claude/claude_desktop_config.json

Tip

If the file doesn’t exist, create it. Claude Desktop reads this file on startup.

Basic Configuration (Single GitHub Account)

Perfect for personal use with one GitHub account.

1. Locate your executable

   Note the full path to your built executable. For example:

   • Windows: C:\Users\YourName\github-mcp-server-v3.exe
   • macOS/Linux: /home/yourname/github-mcp-server-v3

2. Edit the configuration file

   Open claude_desktop_config.json and add:

   claude_desktop_config.json

   {
     "mcpServers": {
       "github-mcp": {
         "command": "C:\\Users\\YourName\\github-mcp-server-v3.exe",
         "args": [],
         "env": {
           "GITHUB_TOKEN": "ghp_your_token_here"
         }
       }
     }
   }

   Windows paths

   On Windows, use double backslashes (\\) in paths or forward slashes (/):

   • ✅ C:\\Users\\Name\\file.exe
   • ✅ C:/Users/Name/file.exe
   • ❌ C:\Users\Name\file.exe (will fail)

3. Restart Claude Desktop

   Close and reopen Claude Desktop to load the new configuration.

4. Verify connection

   In Claude Desktop, try:

   "List my GitHub repositories"

   If configured correctly, you’ll see your repositories listed.

Multi-Profile Configuration (Recommended)

Manage multiple GitHub accounts (personal, work, client projects) from a single executable.

Why Multi-Profile?

• Account separation: Keep personal and work GitHub accounts isolated
• Easy switching: Claude can use the right profile for each context
• Single executable: One binary serves all profiles
• Clear naming: Profile names appear in tool responses

Setup

claude_desktop_config.json

{
  "mcpServers": {
    "github-personal": {
      "command": "C:\\Users\\YourName\\github-mcp-server-v3.exe",
      "args": ["--profile", "personal"],
      "env": {
        "GITHUB_TOKEN": "ghp_personal_token_here"
      }
    },
    "github-work": {
      "command": "C:\\Users\\YourName\\github-mcp-server-v3.exe",
      "args": ["--profile", "work"],
      "env": {
        "GITHUB_TOKEN": "ghp_work_token_here"
      }
    },
    "github-client-acme": {
      "command": "C:\\Users\\YourName\\github-mcp-server-v3.exe",
      "args": ["--profile", "client-acme"],
      "env": {
        "GITHUB_TOKEN": "ghp_client_token_here"
      }
    }
  }
}

Using Profiles

In Claude Desktop, specify which profile to use:

"Using my work GitHub account, list all repositories"
→ Claude uses the github-work profile

"On my personal account, create a new repository called 'my-project'"
→ Claude uses the github-personal profile

Or let Claude infer from context:

"Show me the PRs on my personal dotfiles repo"
→ Claude uses github-personal

"What security alerts do we have at Acme Corp?"
→ Claude uses github-client-acme

Safety Configuration (Optional)

Configure the 4-tier safety system to control risk-based confirmations.

Create safety.json in the same directory as your executable:

safety.json

{
  "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,
  "enable_auto_backup": false,
  "backup_path": "./backups"
}

Safety Modes

Mode	Confirms From	Use Case
strict	MEDIUM+	Production environments, shared repos
moderate	HIGH+	General use (default)
permissive	CRITICAL	Local development, personal repos
disabled	Never	⚠️ Not recommended

Default if no safety.json exists: moderate mode with audit logging enabled.

Configuration Options

Option	Type	Default	Description
mode	string	"moderate"	Safety mode (strict/moderate/permissive/disabled)
enable_audit_log	boolean	true	Enable JSON audit logging
require_confirmation_above	number	3	Risk level requiring confirmation (1=LOW, 2=MEDIUM, 3=HIGH, 4=CRITICAL)
audit_log_path	string	"./mcp-admin-audit.log"	Path to audit log file
audit_log_max_size_mb	number	10	Max log size before rotation (MB)
audit_log_max_backups	number	5	Number of rotated log files to keep
enable_auto_backup	boolean	false	Automatic backups before destructive operations
backup_path	string	"./backups"	Directory for automatic backups

Custom Safety Config Path

Specify a custom safety.json location:

claude_desktop_config.json

{
  "mcpServers": {
    "github-mcp": {
      "command": "C:\\path\\to\\github-mcp-server-v3.exe",
      "args": ["--safety-config", "C:\\path\\to\\custom-safety.json"],
      "env": {
        "GITHUB_TOKEN": "ghp_token_here"
      }
    }
  }
}

Verifying Configuration

Check MCP Connection

In Claude Desktop, look for the server status indicator:

• ✅ Green indicator: Connected successfully
• ❌ Red indicator: Connection failed (check configuration and restart)

Test a Simple Tool

Try a read-only operation to verify:

"What's the Git status of my current repository?"

Expected: Tool executes successfully or returns “No Git repository found” (if not in a Git directory).

Test GitHub API Connection

"List my GitHub repositories"

Expected: Your GitHub repositories are listed.

Troubleshooting

Server doesn’t appear in Claude Desktop

Cause: Configuration syntax error or Claude Desktop not restarted.

Fix:

1. Validate JSON syntax (use jsonlint.com)
2. Check path uses double backslashes on Windows
3. Completely quit and restart Claude Desktop

”Authentication failed” errors

Cause: Invalid or expired GitHub token.

Fix:

1. Verify token in GitHub Settings
2. Check token has repo scope minimum
3. Generate new token if expired

”Command not found” errors

Cause: Incorrect executable path.

Fix:

1. Verify the full path is correct
2. On Windows, use \\ or / in paths
3. Check the executable exists at that location

Tools work but admin tools fail

Cause: Token lacks admin permissions on the target repository.

Fix:

1. Verify you have admin access to the repository
2. Check token includes optional scopes:
   • delete_repo for repository deletion
   • admin:repo_hook for webhook management
   • admin:org for team management

Next Steps

Configuration complete! Now explore the available tools:

• Git Operations → — Local Git workflow (0 tokens)
• GitHub API → — Repository and PR management
• Admin Tools → — Repository settings, webhooks, collaborators
• Safety System → — Understand risk levels and confirmation workflows