Security Best Practices

GitHub Token Permissions

The GitHub MCP Server requires a Personal Access Token (PAT) with appropriate scopes.

Required Scope (Minimum)

repo — Full control of private repositories

This scope is essential for:

• All repository read/write operations
• Issue and PR management
• Webhook management
• Collaborator management
• Branch protection rules

Why repo scope?

The repo scope provides comprehensive repository access. More granular scopes exist in theory, but GitHub’s permission model requires repo for most operations.

Optional Scopes (Recommended)

Scope	Purpose	Required For
delete_repo	Repository deletion	github_delete_repository tool
workflow	GitHub Actions	github_rerun_workflow tool
security_events	Security alerts	Alert dismissal tools (Dependabot, Code Scanning, Secret Scanning)
admin:repo_hook	Enhanced webhooks	Advanced webhook management (v3.0)
admin:org	Organization teams	Team management in organization repos (v3.0)

Creating a Token

1. Navigate to GitHub Settings

   Go to: https://github.com/settings/tokens

2. Click “Generate new token (classic)”

   Choose “Generate new token (classic)” not “Fine-grained tokens” (limited support currently).

3. Configure token

   • Note: Claude Desktop MCP Server - [Profile Name]
   • Expiration: 90 days (recommended) or custom
   • Scopes: Select as needed (see above)

4. Generate and copy token

   ⚠️ Copy immediately — you won’t see it again!

5. Store securely

   Add to Claude Desktop config:

   {
     "mcpServers": {
       "github-mcp": {
         "command": "path/to/github-mcp-server-v3.exe",
         "env": {
           "GITHUB_TOKEN": "ghp_your_token_here"
         }
       }
     }
   }

Token Security Best Practices

DO

• ✅ Use specific token notes (e.g., “Claude Desktop - Personal”)
• ✅ Set expiration dates (90 days recommended)
• ✅ Use separate tokens for different profiles
• ✅ Revoke tokens when no longer needed
• ✅ Rotate tokens regularly
• ✅ Store tokens in environment variables or secure config files

DON’T

• ❌ Commit tokens to version control (.env in .gitignore)
• ❌ Share tokens between machines or users
• ❌ Use tokens with broader permissions than needed
• ❌ Leave tokens without expiration (security risk)
• ❌ Reuse personal tokens for automation (create dedicated tokens)

Token Rotation

Rotate tokens every 90 days:

1. Generate new token with same scopes
2. Update claude_desktop_config.json with new token
3. Restart Claude Desktop
4. Verify connection works
5. Revoke old token in GitHub Settings

Built-in Security Features

The MCP GitHub Server includes multiple security layers.

Input Validation

Every parameter is validated against specific attack vectors.

Path Traversal Prevention (CWE-22)

Attack example:

{
  "owner": "../../../etc",
  "repo": "passwd"
}

Protection:

• Detects .., /, \ in owner/repo parameters
• Returns ValidationError before API call
• Prevents directory traversal attacks

Command Injection Prevention (CWE-78)

Attack example:

{
  "branch": "main; rm -rf /"
}

Protection:

• Validates branch names against allowed character set
• Blocks dangerous characters (;, |, `, $, &)
• Uses parameterized Git commands (no shell interpolation)

SSRF Prevention

Server-Side Request Forgery protection for webhook URLs.

Blocked URL patterns:

http://localhost:8080/webhook         ❌ Localhost
http://127.0.0.1/webhook              ❌ Loopback
http://192.168.1.100/webhook          ❌ Private network
http://10.0.0.1/webhook               ❌ Private network
http://169.254.169.254/metadata       ❌ Cloud metadata
file:///etc/passwd                     ❌ File protocol

Allowed:

https://api.example.com/webhook       ✅ Public HTTPS
https://hooks.slack.com/...            ✅ Public service

Parameter Sanitization

Sensitive parameters are automatically redacted in:

• Audit logs: secret, token, password fields show [REDACTED]
• Error messages: Tokens not leaked in errors
• Debug output: API tokens not logged

Network Security

TLS/HTTPS Only

All GitHub API communication uses HTTPS:

• ✅ TLS 1.2+ encryption
• ✅ Certificate validation enabled
• ✅ No insecure HTTP fallback

No Credential Storage

The server:

• ❌ Does NOT store tokens to disk
• ❌ Does NOT cache credentials
• ✅ Reads token from environment on startup
• ✅ Keeps token in memory only
• ✅ Token cleared on process termination

Rate Limit Awareness

Server tracks and respects GitHub API rate limits:

• Reports remaining quota
• Warns before exhaustion
• Includes rate limit headers in responses

Operational Security

Multi-Profile Isolation

When using multiple profiles:

• Each profile has dedicated token
• Token scopes can differ per profile
• Audit logs track operations by profile
• No cross-profile token sharing

Example:

{
  "mcpServers": {
    "github-personal": {
      "env": { "GITHUB_TOKEN": "ghp_personal..." }
    },
    "github-work": {
      "env": { "GITHUB_TOKEN": "ghp_work..." }
    }
  }
}

Audit Trail

All administrative operations logged:

• Timestamp (ISO 8601)
• Operation name and parameters
• Risk level and confirmation token
• Result (success/failure)
• Rollback command for reversibility

Compliance: Audit logs support:

• Security incident investigation
• Access control audits
• Regulatory compliance (SOC 2, ISO 27001)

Principle of Least Privilege

Repository access:

• Admin tools require admin repository access
• Read-only tools work with read-only access
• Server doesn’t request elevated permissions

Token scopes:

• Start with minimal repo scope
• Add optional scopes only when needed
• Separate tokens for different privilege levels

Common Security Scenarios

Scenario 1: Token Leaked in Logs

Problem: Accidentally committed .env file with token to Git.

Response:

1. Immediately revoke token in GitHub Settings
2. Remove from Git history: Use git filter-repo or BFG Repo-Cleaner
3. Generate new token with different value
4. Update Claude Desktop config with new token
5. Verify no unauthorized access in GitHub audit log

Scenario 2: Suspicious API Activity

Problem: GitHub audit log shows unexpected API calls.

Response:

1. Check MCP audit log (mcp-admin-audit.log) for matching operations
2. Revoke token if compromise suspected
3. Review GitHub Security Log for unauthorized access
4. Enable 2FA if not already active
5. Rotate all tokens as precaution

Scenario 3: Accidental Repository Deletion

Problem: Confirmation token used for wrong repository.

Response:

1. Contact GitHub Support immediately — deletion is permanent but GitHub may help within 90 days
2. Check backups (local clones, CI/CD mirrors)
3. Review audit log to understand what happened
4. Update safety config to stricter mode
5. Implement backup policy before future deletions

Compliance Considerations

Data Handling

The server:

• Does NOT store repository data to disk (except local Git operations)
• Does NOT transmit data to third parties (only GitHub API)
• Does NOT log file contents (only metadata)
• Does log administrative actions (audit log)

GDPR Considerations

If operating in EU:

• GitHub tokens contain user identity → personal data
• Store tokens securely (encrypted config file)
• Delete tokens when user access removed
• Audit logs may contain usernames → handle per GDPR

SOC 2 / ISO 27001

For compliance:

• ✅ Enable audit logging
• ✅ Use strict safety mode
• ✅ Rotate tokens every 90 days
• ✅ Implement backup policy
• ✅ Regular security reviews
• ✅ Restrict admin tool access

Security Checklist

Initial Setup

• Generated token with minimal scopes required
• Set token expiration (90 days max)
• Stored token in environment variable (not committed)
• Tested connection with read-only operation
• Configured safety mode appropriately
• Enabled audit logging

Regular Maintenance

• Rotate tokens every 90 days
• Review audit logs monthly
• Check GitHub Security Log for anomalies
• Update server to latest version
• Review and revoke unused tokens
• Verify backup integrity

Before Administrative Operations

• Verify correct repository/owner
• Understand operation consequences
• Check if operation is reversible
• Create manual backup if CRITICAL
• Note rollback command from confirmation
• Verify no typos in parameters

Reporting Security Issues

Found a security vulnerability in the GitHub MCP Server?

Do NOT open a public GitHub issue.

Instead:

1. Email: security@[project-domain].com (if available)
2. Or: Open a GitHub Security Advisory
3. Include: Detailed reproduction steps, impact assessment, suggested fix

Response SLA: 72 hours for acknowledgment, 30 days for fix (critical issues).

Further Reading

• GitHub Token Security Best Practices
• OAuth Scope Documentation
• GitHub Security Log
• OWASP API Security Top 10