GitHub MCP Server

A comprehensive Model Context Protocol server for GitHub integration, providing access to repositories, issues, pull requests, commits, releases, and GitHub Actions workflows.

🔒 Publishing-Safe Setup

This MCP is designed to be safely published without exposing sensitive credentials.

Environment Configuration

DO NOT store your GitHub token in the MCP directory. Instead, use one of these secure methods:

Method 1: External Environment File (Recommended)

Store your environment file outside the project:

# Create secure environment directory
mkdir -p ~/.config/mcp-environments

# Create GitHub environment file
cat > ~/.config/mcp-environments/github.env << EOF
GITHUB_TOKEN=your_personal_access_token
GITHUB_OWNER=your_github_username
EOF

Method 2: Claude Desktop Config (Most Secure)

Store credentials directly in your Claude Desktop configuration (recommended for production).

Features

Repository Management

List repositories with filtering and sorting
Get detailed repository information
Browse branches and file contents
Search code across repositories

Issue Management

List issues with filtering by state, labels, assignee
Get detailed issue information
Create new issues with labels and assignees

Pull Request Management

List pull requests with filtering
Get detailed PR information including stats
Track PR status and mergeability

Commit & Release Tracking

List commits with filtering by date, path, branch
Get detailed commit information with file changes
List releases and get latest release info

🔄 GitHub Actions & Workflows (NEW!)

Workflow Management: List all workflows in repositories
Run Monitoring: Track workflow runs with real-time status updates
Job Details: Get detailed information about individual jobs
Execution Control: Cancel, re-run, or re-run failed jobs
Workflow Dispatch: Trigger workflows with custom inputs
Artifact Management: List and download workflow artifacts
Usage Analytics: Get workflow usage statistics and billing info
Status Tracking: Monitor CI/CD pipeline health with status emojis

User Information

Get authenticated user details
Look up other user profiles

Setup

1. Install Dependencies

cd github-actions-mcp-server
npm install

2. Create GitHub Personal Access Token

Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Tokens (classic)
Create new token with these scopes:
- repo - Full repository access
- actions:read - Read workflow information
- actions:write - Trigger and manage workflows
- read:user - Read user profile data
- read:org - Read organization data (if using organization)

3. Configure Environment

Secure Method: External Environment File

# Create environment file outside project
cat > ~/.config/mcp-environments/github.env << EOF
GITHUB_TOKEN=your_personal_access_token
GITHUB_OWNER=your_github_username
EOF

Most Secure: Claude Desktop Config Only

Add directly to Claude Desktop config with no environment files.

Claude Desktop Configuration

Method 1: External Environment File

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["tsx", "/path/to/github-actions-mcp-server/src/index.ts"],
      "envFile": "~/.config/mcp-environments/github.env"
    }
  }
}

Method 2: Direct Environment Variables (Most Secure)

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["tsx", "/path/to/github-actions-mcp-server/src/index.ts"],
      "env": {
        "GITHUB_TOKEN": "your_personal_access_token",
        "GITHUB_OWNER": "your_github_username"
      }
    }
  }
}

Usage Examples

Once configured, you can ask Claude things like:

Repository & Code Management

"List my repositories sorted by last updated"
"Show me the open issues in my project-name repository"
"Get the content of README.md from my repo"
"What are the recent commits in the main branch?"
"Create an issue titled 'Bug fix needed' in my repo"
"Search for 'authentication' across all my repositories"

🔄 GitHub Actions & Workflows

"Show me all workflows in my repository"
"What are the recent workflow runs for my project?"
"Check the status of workflow run #123"
"Show me failed GitHub Actions runs"
"Cancel the currently running workflow"
"Re-run the failed jobs in the last workflow"
"Trigger the deployment workflow with production environment"
"List artifacts from the latest build"
"How much GitHub Actions usage have I consumed this month?"

Available Tools

Core Repository Tools

list_repositories - List repositories with filtering/sorting
get_repository - Get detailed repository info
get_file_content - Get file/directory content
search_code - Search code across repos
list_issues - List issues with filtering
create_issue - Create new issues
list_pull_requests - List PRs with filtering
list_commits - List commits with filtering
get_user_info - Get user profile information

🔄 GitHub Actions Tools

list_workflows - List all workflows in a repository
get_workflow - Get details of a specific workflow
list_workflow_runs - List workflow runs with status filtering
get_workflow_run - Get detailed information about a specific run
get_workflow_run_jobs - Get jobs for a workflow run
cancel_workflow_run - Cancel a running workflow
rerun_workflow - Re-run an entire workflow
rerun_failed_jobs - Re-run only failed jobs
trigger_workflow_dispatch - Trigger workflows with custom inputs
list_workflow_artifacts - List artifacts from workflow runs
download_artifact - Get artifact download information
get_workflow_usage - Get workflow usage statistics

🔄 Workflow Examples

Monitor CI/CD Pipeline

# Check all recent workflow runs
"Show me the status of recent workflow runs"

# Get detailed information about a specific run
"Get details for workflow run #142"

# Check which jobs failed
"Show me the jobs for workflow run #142"

Automate Deployments

# Trigger a deployment workflow
"Trigger the deploy workflow for production environment"

# With custom inputs
"Run the deploy workflow with version=1.2.3 and environment=staging"

# Monitor deployment progress
"Check the status of the latest deployment workflow"

Troubleshoot Failed Builds

# Find failed runs
"Show me failed workflow runs from the last week"

# Get job details
"What jobs failed in workflow run #140?"

# Re-run failed jobs
"Re-run the failed jobs in workflow #140"

Manage Artifacts

# List available artifacts
"Show me artifacts from the latest build"

# Download specific artifacts
"Get download info for artifact #12345"

Security Notes

✅ Publishing Safe: No sensitive data stored in code repository
✅ Environment Isolation: Credentials stored outside project directory
✅ .gitignore Protection: Comprehensive ignore patterns prevent accidental commits
✅ Minimal Permissions: Only request necessary GitHub scopes
✅ External Storage: Use ~/.config/mcp-environments/ for credentials
✅ Actions Security: Workflow triggers respect repository permissions

Publishing Checklist

Before publishing this MCP:

✅ No .env files in the repository
✅ No hardcoded tokens or credentials
✅ .gitignore includes comprehensive patterns
✅ README documents secure setup methods
✅ Example configurations use placeholders

Troubleshooting

Common Issues

Authentication Failed
- Verify your PAT is correct and has required scopes
- For workflows: ensure token has actions:read and actions:write scopes
- Check that GITHUB_OWNER matches your username/org
Environment File Not Found
- Ensure the environment file path in Claude config is correct
- Check file permissions on the environment file
Rate Limiting
- GitHub API has rate limits (5000 requests/hour for authenticated users)
- The MCP will show rate limit errors if exceeded
Workflow Dispatch Failed
- Ensure the workflow file has workflow_dispatch trigger configured
- Verify workflow inputs match the schema defined in the workflow file
- Check that the branch/ref exists
Cannot Cancel/Re-run Workflows
- Verify your token has actions:write permission
- Ensure you have push access to the repository
- Some workflows may not be cancellable if they're already completed

Version History

v0.2.0 - Added comprehensive GitHub Actions and workflow support
v0.1.0 - Initial release with repository, issues, and PR management

GitHub