# 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
