# 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:
```bash
# 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
```bash
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**
```bash
# 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**
```json
{
  "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)**
```json
{
  "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