GitHub MCP Server Documentation¶

Overview¶

The GitHub MCP Server template now uses a custom MCP server image that wraps and extends the official GitHub MCP server. This enables support for platform-wide template variables and configuration management, providing a consistent experience across all MCP templates.

Our platform extends the official GitHub MCP server by providing: - 🚀 One-Command Deployment: Deploy and manage GitHub MCP servers with a single command - 🔧 Dynamic Tool Discovery: Automatically discover and catalog all 77+ available GitHub tools - 📊 Comprehensive Monitoring: Built-in logging, status monitoring, and error tracking - 🔄 Auto-Scaling: Docker-based deployment with automatic container management - ⚙️ Configuration Management: Simplified environment variable and secret management - 🛡️ Security: Secure token handling and access control - 📈 Performance Optimization: Efficient caching and connection pooling

Available Tools (77 Total)¶

The GitHub MCP server provides comprehensive GitHub API access through 77 specialized tools organized by functionality:

Repository Management¶

create_repository: Create new GitHub repositories
fork_repository: Fork repositories to your account or organization
search_repositories: Search for GitHub repositories
get_file_contents: Read file contents from repositories
create_or_update_file: Create or update files in repositories
delete_file: Delete files from repositories
push_files: Push multiple files in a single commit

Branch & Tag Management¶

create_branch: Create new branches
list_branches: List all repository branches
get_tag: Get git tag details
list_tags: List all repository tags
get_commit: Get commit details
list_commits: List repository commits

Issue Management¶

create_issue: Create new issues
get_issue: Get issue details
update_issue: Update existing issues
list_issues: List repository issues
search_issues: Search issues across repositories
add_issue_comment: Add comments to issues
get_issue_comments: Get issue comments
add_sub_issue: Add sub-issues to parent issues
list_sub_issues: List sub-issues for an issue
remove_sub_issue: Remove sub-issues
reprioritize_sub_issue: Reorder sub-issues

Pull Request Management¶

create_pull_request: Create new pull requests
get_pull_request: Get pull request details
update_pull_request: Update existing pull requests
list_pull_requests: List repository pull requests
search_pull_requests: Search pull requests
merge_pull_request: Merge pull requests
get_pull_request_comments: Get PR comments
get_pull_request_diff: Get PR diff
get_pull_request_files: Get changed files in PR
get_pull_request_reviews: Get PR reviews
get_pull_request_status: Get PR status
update_pull_request_branch: Update PR branch

Code Review & Comments¶

create_pending_pull_request_review: Create pending reviews
add_comment_to_pending_pull_request_review: Add review comments
submit_pending_pull_request_review: Submit reviews
delete_pending_pull_request_review: Delete pending reviews
create_and_submit_pull_request_review: Create and submit reviews
request_copilot_review: Request GitHub Copilot reviews
assign_copilot_to_issue: Assign Copilot to issues

GitHub Actions & Workflows¶

list_workflows: List repository workflows
run_workflow: Trigger workflow runs
get_workflow_run: Get workflow run details
list_workflow_runs: List workflow runs
cancel_workflow_run: Cancel running workflows
rerun_workflow_run: Re-run entire workflows
rerun_failed_jobs: Re-run only failed jobs
list_workflow_jobs: List workflow jobs
get_job_logs: Get job logs
get_workflow_run_logs: Get complete workflow logs
get_workflow_run_usage: Get workflow usage metrics
list_workflow_run_artifacts: List workflow artifacts
download_workflow_run_artifact: Download artifacts
delete_workflow_run_logs: Delete workflow logs

Security & Scanning¶

list_code_scanning_alerts: List code scanning alerts
get_code_scanning_alert: Get specific code scanning alerts
list_dependabot_alerts: List Dependabot alerts
get_dependabot_alert: Get specific Dependabot alerts
list_secret_scanning_alerts: List secret scanning alerts
get_secret_scanning_alert: Get specific secret scanning alerts

Discussions¶

list_discussions: List repository discussions
get_discussion: Get discussion details
get_discussion_comments: Get discussion comments
list_discussion_categories: List discussion categories

Notifications & Activity¶

list_notifications: List GitHub notifications
get_notification_details: Get notification details
dismiss_notification: Mark notifications as read
mark_all_notifications_read: Mark all notifications read
manage_notification_subscription: Manage notification settings
manage_repository_notifications: Manage repository notifications

Search & Discovery¶

search_code: Search code across repositories
search_users: Search GitHub users
search_orgs: Search GitHub organizations

User & Profile¶

get_me: Get authenticated user details

Quick Start¶

Installation¶

Deploy the GitHub MCP server using our platform:

# Deploy with automatic configuration
python -m mcp_template deploy github

# Deploy with custom configuration
python -m mcp_template deploy github --config GITHUB_PERSONAL_ACCESS_TOKEN="your_token"

# Check deployment status
mcp-template status github

# View real-time logs
python -m mcp_template logs github

Configuration¶

The template requires a GitHub Personal Access Token for authentication:

Variable	Description	Required	Default
`GITHUB_PERSONAL_ACCESS_TOKEN`	GitHub Personal Access Token with appropriate scopes	Yes	-
`LOG_LEVEL`	Logging level (DEBUG, INFO, WARNING, ERROR)	No	INFO

Creating a GitHub Token¶

Go to GitHub Settings → Developer settings → Personal access tokens
Generate a new token with required scopes:
repo - Full repository access
workflow - GitHub Actions access
notifications - Notification access
security_events - Security alert access

Usage Examples¶

Repository Operations¶

# List repository files
mcp-client call get_file_contents --owner "octocat" --repo "Hello-World" --path "README.md"

# Create a new file
mcp-client call create_or_update_file --owner "user" --repo "repo" --path "new_file.py" --content "print('Hello')" --message "Add new file"

# Create a new repository
mcp-client call create_repository --name "my-new-repo" --description "A new repository"

Issue Management¶

# Create an issue
mcp-client call create_issue --owner "user" --repo "repo" --title "Bug Report" --body "Found a bug"

# Add a comment to an issue
mcp-client call add_issue_comment --owner "user" --repo "repo" --issue_number 1 --body "Working on this"

# Search for issues
mcp-client call search_issues --query "is:open label:bug"

Pull Request Workflow¶

# Create a pull request
mcp-client call create_pull_request --owner "user" --repo "repo" --title "Feature" --head "feature-branch" --base "main"

# Review a pull request
mcp-client call create_pending_pull_request_review --owner "user" --repo "repo" --pull_number 1
mcp-client call add_comment_to_pending_pull_request_review --body "Looks good!"
mcp-client call submit_pending_pull_request_review --event "APPROVE"

GitHub Actions¶

# List workflows
mcp-client call list_workflows --owner "user" --repo "repo"

# Trigger a workflow
mcp-client call run_workflow --owner "user" --repo "repo" --workflow_id "deploy.yml"

# Get workflow run logs
mcp-client call get_job_logs --owner "user" --repo "repo" --run_id 123456 --failed_only true

Tool Discovery¶

Our platform provides dynamic tool discovery to automatically catalog all available GitHub tools:

# Discover all available tools
mcp-template tools github --config GITHUB_PERSONAL_ACCESS_TOKEN="your_token"

# Refresh tool cache
mcp-template tools github --refresh

# Get detailed tool information
mcp-template tools github --verbose

Platform Benefits¶

Enhanced Deployment¶

Docker Integration: Seamless container-based deployment
Environment Management: Secure handling of GitHub tokens
Health Monitoring: Automatic health checks and restart policies
Port Management: Automatic port allocation and management

Advanced Tooling¶

Real-time Discovery: Dynamic discovery of all 77 GitHub tools
Intelligent Caching: Tool information caching for improved performance
Error Handling: Robust error handling and retry mechanisms
Logging: Comprehensive request/response logging

Developer Experience¶

One-Command Setup: Deploy GitHub integration in seconds
Interactive CLI: Rich terminal interface with progress indicators
Comprehensive Documentation: Auto-generated tool documentation
Testing Integration: Built-in testing framework for GitHub operations

Configuration Options¶

Property	Type	Environment Variable	Default	Description
`log_level`	string	`LOG_LEVEL`	`INFO`	Logging level (DEBUG, INFO, WARNING, ERROR)
`mcp_transport`	string	`MCP_TRANSPORT`	`stdio`	MCP transport mode (stdio only supported)
`mcp_port`	integer	`MCP_PORT`	`7071`	Port for MCP server (not used for stdio)
`github_token`	string	`GITHUB_PERSONAL_ACCESS_TOKEN`	``	GitHub personal access token
`github_host`	string	`GITHUB_HOST`	`https://api.github.com`	GitHub host URL (default: https://api.github.com)
`github_toolset`	string	`GITHUB_TOOLSET`	`all`	GitHub toolset to use (default: 'default'). Options: 'context', 'actions', 'code_security', 'dependabot', 'discussions', 'experiments', 'gists', 'issues', 'notifications', 'orgs', 'pull_requests', 'repos', 'secret_protection', 'users'. If 'all', all toolsets are enabled. Use comma-separated values to specify multiple toolsets.
`dynamic_toolsets`	integer	`GITHUB_DYNAMIC_TOOLSETS`	`0`	Enable dynamic toolset discovery (default: 0)
`read_only`	integer	`GITHUB_READ_ONLY`	`0`	When 1, restricts server to read-only operations for enhanced security

Usage Examples¶

# Deploy with configuration
python -m mcp_template deploy github --show-config

# Using environment variables
python -m mcp_template deploy github --env LOG_LEVEL=value

# Using CLI configuration
python -m mcp_template deploy {template_id} --config {first_prop}=value

# Using nested configuration
python -m mcp_template deploy {template_id} --config category__property=value

Development¶

Local Development¶

# Clone and set up local development
git clone <repository-url>
cd github-template

# Install dependencies
pip install -r requirements.txt

# Set environment variables
export GITHUB_PERSONAL_ACCESS_TOKEN="your_token"
export LOG_LEVEL="DEBUG"

# Run the server locally
python -m server

Testing¶

# Run all tests
pytest tests/ -v

# Run integration tests
pytest tests/test_github_integration.py

# Test with real GitHub API (requires token)
pytest tests/ --github-token="your_token"

Docker Development¶

# Build local image
docker build -t github-mcp-local .

# Run with environment variables
docker run -e GITHUB_PERSONAL_ACCESS_TOKEN="your_token" github-mcp-local

# Run with our platform
python -m mcp_template deploy github --local

Monitoring & Troubleshooting¶

Health Checks¶

# Check service status
mcp-template status github

# Get detailed health information
mcp-template status github --detailed

# View real-time logs
python -m mcp_template logs github --follow

Common Issues¶

Authentication Errors
Verify GitHub token has correct scopes
Check token expiration date
Ensure token is properly set in environment
Rate Limiting
GitHub API has rate limits (5000 requests/hour for authenticated users)
Use conditional requests when possible
Consider GitHub Apps for higher limits
Permission Errors
Verify repository access permissions
Check organization policies
Ensure token has required scopes
Network Issues
Check GitHub API status at https://www.githubstatus.com/
Verify network connectivity
Check firewall settings

Debug Mode¶

Enable comprehensive debugging:

# Deploy with debug logging
python -m mcp_template deploy github --config LOG_LEVEL="DEBUG"

# View debug logs
python -m mcp_template logs github --level debug

# Enable trace logging for API calls
python -m mcp_template logs github --trace

Security¶

Token Management¶

Secure Storage: Tokens are stored securely and never logged
Scope Validation: Automatic validation of token scopes
Rotation Support: Easy token rotation without service interruption

Access Control¶

Principle of Least Privilege: Request only necessary GitHub scopes
Audit Logging: All API calls are logged for audit purposes
Error Sanitization: Sensitive information is never exposed in error messages

Performance Optimization¶

Caching Strategy¶

Tool Discovery Cache: Cache discovered tools for improved performance
Response Caching: Cache frequently accessed GitHub data
Connection Pooling: Efficient HTTP connection management

Rate Limit Management¶

Intelligent Throttling: Automatic rate limit respect
Request Batching: Batch compatible requests
Priority Queuing: Prioritize critical operations

API Reference¶

All 77 GitHub tools are available through the MCP interface. Each tool includes: - Input Schema: Detailed parameter specifications - Output Schema: Response format documentation - Error Handling: Comprehensive error response patterns - Examples: Real-world usage examples

For detailed API documentation of each tool, use:

mcp-template tools github --tool-name <tool_name> --detailed

Contributing¶

We welcome contributions to improve the GitHub MCP server template:

Bug Reports: Submit issues with detailed reproduction steps
Feature Requests: Propose new GitHub integrations
Pull Requests: Contribute code improvements
Documentation: Help improve this documentation

See the main repository's contributing guidelines for detailed information.

License¶

This template extends the official GitHub MCP server and is part of the MCP Server Templates project. See LICENSE for details.

Support¶

For support, please open an issue in the main repository or contact the maintainers.