# GitHub MCP Setup Guide
## 🔧 Quick Setup
### 1. Installation
```bash
cd path/to/your/github-mcp
npm install
```
### 2. GitHub Personal Access Token
1. Go to GitHub → Settings → Developer Settings → Personal Access Tokens → Tokens (classic)
2. Click "Generate new token (classic)"
3. Give it a name like "GitHub MCP"
4. Select these scopes:
- **repo** (Full repository access)
- **actions:read** (Read workflow information)
- **actions:write** (Trigger and manage workflows)
- **read:user** (Read user profile)
- **read:org** (Read organization data - if using org)
5. Copy the token for configuration
### 3. Configure Environment
#### **Method 1: Claude Desktop Config (Recommended)**
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["tsx", "/path/to/github-mcp/src/index.ts"],
"env": {
"GITHUB_TOKEN": "your_personal_access_token",
"GITHUB_OWNER": "your_github_username"
}
}
}
}
```
#### **Method 2: Environment File**
```bash
# Create environment file
cat > .env << EOF
GITHUB_TOKEN=your_personal_access_token
GITHUB_OWNER=your_github_username
EOF
```
### 4. Restart Claude Desktop
Quit and reopen Claude Desktop to load the new MCP server.
## 🚀 Usage Examples
### Repository Management
- "List my repositories"
- "Show me details for my project-name repository"
- "Get the README.md from my project-name"
### GitHub Actions & Workflows ⭐ **NEW!**
- "Show me all workflows in my project"
- "What are the recent workflow runs?"
- "Trigger the deployment workflow"
- "Check the status of workflow run #123"
- "Cancel the running workflow"
- "Re-run failed jobs in the last workflow"
### Issues & Pull Requests
- "Show me open issues in project-name"
- "Create an issue titled 'Fix bug' in project-name"
- "List pull requests in project-name"
### Code Search & History
- "Search for 'authentication' in my code"
- "Show me recent commits in project-name"
- "What's my GitHub profile info?"
## 🛠️ Available Tools
### **Repository Management (9 tools)**
- list_repositories, get_repository, get_file_content
- search_code, list_issues, create_issue
- list_pull_requests, list_commits, get_user_info
### **🔄 GitHub Actions & Workflows (13 tools)** ⭐ **NEW!**
- list_workflows, get_workflow, list_workflow_runs
- get_workflow_run, get_workflow_run_jobs
- cancel_workflow_run, rerun_workflow, rerun_failed_jobs
- trigger_workflow_dispatch, list_workflow_artifacts
- download_artifact, get_workflow_usage
## 🔒 Security Features
- ✅ Environment-based token configuration
- ✅ No hardcoded credentials
- ✅ Secure API authentication
- ✅ Publishing-safe codebase
## 🐛 Troubleshooting
### Common Issues
1. **Authentication Failed** - Verify token has correct scopes
2. **Rate Limiting** - GitHub API limits to 5000 requests/hour
3. **Workflow Dispatch Failed** - Ensure workflow has `workflow_dispatch` trigger
Your GitHub MCP with workflow capabilities is ready! 🎯
