awaybreaktoday/github-actions-mcp-server

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

1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Tokens (classic)
2. 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

1. 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

2. Environment File Not Found

   • Ensure the environment file path in Claude config is correct
   • Check file permissions on the environment file

3. Rate Limiting

   • GitHub API has rate limits (5000 requests/hour for authenticated users)
   • The MCP will show rate limit errors if exceeded

4. 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

5. 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