GitHub
Repository management, issues, and pull requests
Connect GitHub
Connect your GitHub account with a single command:
mcp-shield providers connect github
# Output:
# Opening browser to authorize GitHub...
# ✓ GitHub connected successfully
# Connected as: your-username
# Scopes: repo, read:org, read:userOr connect via the MCP Shield dashboard for a visual OAuth flow.
Scopes
The GitHub integration requests the following OAuth scopes:
| Scope | Description | Required |
|---|---|---|
| repo | Full control of private repositories | Required |
| read:org | Read organization membership | Required |
| read:user | Read user profile data | Required |
| write:repo_hook | Write repository webhooks | Optional |
| delete_repo | Delete repositories | Optional |
Connect with specific scopes using the --scopes flag:
mcp-shield providers connect github --scopes repo,read:orgMCP Tools
The GitHub integration provides 15 MCP tools:
| Tool | Description | Risk |
|---|---|---|
| github:list_repos | List repositories for the authenticated user | low |
| github:get_repo | Get details of a specific repository | low |
| github:create_repo | Create a new repository | medium |
| github:delete_repo | Delete a repository | high |
| github:list_issues | List issues in a repository | low |
| github:create_issue | Create a new issue | low |
| github:update_issue | Update an existing issue | low |
| github:list_pull_requests | List pull requests in a repository | low |
| github:create_pull_request | Create a pull request | medium |
| github:merge_pull_request | Merge a pull request | high |
| github:get_file_contents | Get contents of a file | low |
| github:create_or_update_file | Create or update a file | medium |
| github:list_branches | List branches in a repository | low |
| github:create_branch | Create a new branch | low |
| github:search_code | Search code across repositories | low |
Usage Examples
List repositories
mcp-shield mcp invoke github:list_repos --input '{"limit": 5}'
# Output:
# ┌─────────────────────────┬───────────┬──────────────┐
# │ Repository │ Visibility│ Last Updated │
# ├─────────────────────────┼───────────┼──────────────┤
# │ your-org/project-a │ private │ 2 hours ago │
# │ your-org/project-b │ public │ 1 day ago │
# └─────────────────────────┴───────────┴──────────────┘Create an issue
mcp-shield mcp invoke github:create_issue --input '{
"repo": "your-org/project-a",
"title": "Bug: Login not working",
"body": "Users are unable to log in when...",
"labels": ["bug", "high-priority"]
}'Create a pull request
mcp-shield mcp invoke github:create_pull_request --input '{
"repo": "your-org/project-a",
"title": "feat: Add user authentication",
"head": "feature/auth",
"base": "main",
"body": "This PR adds user authentication..."
}'Policy Recommendations
We recommend the following policies for GitHub:
Protect main branch
Block direct commits and force merges to main or master.
Require approval for high-risk operations
Require manual approval for delete_repo and merge_pull_request.
DLP for code content
Scan create_or_update_file operations for secrets and credentials.
Security Considerations
- Token security: GitHub OAuth tokens are encrypted at rest and never exposed to AI clients.
- Automatic refresh: Tokens are automatically refreshed before expiration.
- Audit logging: All GitHub MCP calls are logged with full context.
- Scope limits: MCP tools only work within the granted OAuth scopes.
Troubleshooting
OAuth callback error
Make sure you're logged in to the correct GitHub account and have permissions for the requested scopes. Try disconnecting and reconnecting.
Repository not found
Ensure the connected GitHub account has access to the repository. For organization repos, you may need to grant organization access.
Token expired
Run mcp-shield providers refresh github to refresh your credentials.