github-actions-mcp
A Model Context Protocol (MCP) server for GitHub Actions integration. Give your AI assistant eyes on your CI/CD pipelines.
Status: Beta (v0.2.0)
Author: Claude + MOD License: MIT
Organization: ArkTechNWA
Quick Start
# 1. Clone and build
git clone https://github.com/ArkTechNWA/github-actions-mcp.git
cd github-actions-mcp
npm install && npm run build
# 2. Add to Claude Code
claude mcp add --transport stdio github-actions -- \
bash -c "GITHUB_TOKEN=\$(gh auth token) node $(pwd)/build/index.js"
# 3. Restart Claude Code and use
# gha_list_workflows, gha_list_runs, gha_diagnose_failure, etc.
Why?
Your AI assistant can write code, but it's blind to whether it passes CI. It can suggest fixes, but can't see the actual error logs from your failed workflow. It can't trigger a deployment or re-run a flaky test.
github-actions-mcp connects Claude to your GitHub Actions workflows — safely.
Philosophy
- Safety by default — Read-only access to workflows and runs
- User controls exposure — Whitelist repos, permission levels
- Never hang — GitHub API timeouts, circuit breakers
- Structured output — JSON for machines, summaries for AI
- Fallback AI — Haiku for log analysis and failure diagnosis
Features
Perception (Read)
- List workflows in a repository
- Get workflow run history and status
- Stream/fetch run logs
- Check job and step status
- View workflow file definitions
Action (Write)
- Trigger workflow_dispatch events
- Re-run failed jobs
- Cancel running workflows
- Enable/disable workflows
Analysis (Optional AI Fallback)
- "Why did this build fail?" synthesis
- Log pattern analysis
- Flaky test detection
Permission Model
Permission Levels
| Level | Description | Default |
|---|---|---|
read | List workflows, runs, logs | ON |
trigger | Dispatch workflows, re-run jobs | OFF |
cancel | Cancel running workflows | OFF |
admin | Enable/disable workflows | OFF |
Repository Filtering
{
"permissions": {
"read": true,
"trigger": false,
"cancel": false,
"admin": false,
"whitelist_repos": [
"ArktechNWA/*",
"myorg/myapp"
],
"blacklist_repos": [
"*/infrastructure",
"*/secrets-*"
]
}
}
Rules:
- Blacklist always wins
- Empty whitelist = all accessible repos allowed
- Patterns support
org/*and*/repowildcards
Bypass Mode
github-actions-mcp --bypass-permissions
Full access to all repos you can see. You own the consequences.
Authentication
GitHub Personal Access Token (classic or fine-grained):
# Environment variable
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx
# Or in config
{
"auth": {
"token_env": "GITHUB_TOKEN"
}
}
Required scopes:
repo(for private repos)actions:read(minimum for read-only)actions:write(for trigger/cancel)
Tools
Workflows
gha_list_workflows
List workflows in a repository.
gha_list_workflows({
repo: string, // "owner/repo"
state?: "active" | "disabled" | "all"
})
gha_get_workflow
Get workflow definition and metadata.
gha_get_workflow({
repo: string,
workflow: string | number // workflow file name or ID
})
Runs
gha_list_runs
List workflow runs with filtering.
gha_list_runs({
repo: string,
workflow?: string, // filter by workflow
branch?: string, // filter by branch
status?: "queued" | "in_progress" | "completed",
conclusion?: "success" | "failure" | "cancelled" | "skipped",
limit?: number // default: 10
})
Returns:
{
"runs": [
{
"id": 12345,
"workflow": "CI",
"status": "completed",
"conclusion": "failure",
"branch": "main",
"commit": "abc1234",
"commit_message": "Fix login bug",
"triggered_by": "push",
"started_at": "2025-12-29T10:00:00Z",
"duration": "3m 42s",
"status_icon": "✗"
}
],
"summary": "Last 10 runs: 7 passed, 2 failed, 1 cancelled"
}
gha_get_run
Get detailed run information including jobs.
gha_get_run({
repo: string,
run_id: number,
include_jobs?: boolean // default: true
})
gha_get_run_logs
Fetch logs for a workflow run.
gha_get_run_logs({
repo: string,
run_id: number,
job?: string, // specific job name
step?: string, // specific step name
grep?: string, // filter log lines
tail?: number // last N lines
})
Actions
gha_trigger_workflow
Trigger a workflow_dispatch event. Requires trigger permission.
gha_trigger_workflow({
repo: string,
workflow: string, // workflow file name
ref: string, // branch or tag
inputs?: Record<string, string> // workflow inputs
})
gha_rerun_workflow
Re-run a workflow. Requires trigger permission.
gha_rerun_workflow({
repo: string,
run_id: number,
failed_only?: boolean // only re-run failed jobs
})
gha_cancel_run
Cancel a running workflow. Requires cancel permission.
gha_cancel_run({
repo: string,
run_id: number
})
gha_set_workflow_state
Enable or disable a workflow. Requires admin permission.
gha_set_workflow_state({
repo: string,
workflow: string,
enabled: boolean
})
Analysis
gha_diagnose_failure
AI-powered failure diagnosis. Gathers logs and context.
gha_diagnose_failure({
repo: string,
run_id: number,
use_ai?: boolean // use Haiku for synthesis
})
Returns:
{
"run_id": 12345,
"workflow": "CI",
"conclusion": "failure",
"failed_jobs": ["test"],
"failed_steps": ["Run pytest"],
"error_context": "[... relevant log lines ...]",
"synthesis": {
"analysis": "Test failed due to missing fixture. The 'db' fixture was removed in commit abc123 but test_user.py still depends on it.",
"suggested_fix": "Either restore the db fixture or update test_user.py to use the new database setup",
"confidence": "high"
}
}
NEVERHANG Architecture
GitHub API can be slow. Log downloads can hang. We guarantee responsiveness.
Timeouts
- API calls: 30s default
- Log downloads: 60s default
- Configurable per-operation
Streaming
- Large logs streamed in chunks
- Progress updates for long downloads
- Client can cancel anytime
Circuit Breaker
- 3 failures in 60s → 5 minute cooldown
- Respects GitHub rate limits (5000/hour)
- Backs off on 403/429 responses
Rate Limit Awareness
{
"rate_limit": {
"remaining": 4892,
"reset_at": "2025-12-29T11:00:00Z"
}
}
Fallback AI
Optional Haiku integration for log analysis.
{
"fallback": {
"enabled": true,
"model": "claude-haiku-4-5",
"api_key_env": "GHA_MCP_FALLBACK_KEY",
"max_log_lines": 500,
"max_tokens": 500
}
}
When used:
gha_diagnose_failurewithuse_ai: true- Complex multi-job failures
- Pattern detection in flaky tests
Configuration
Config File
~/.config/github-actions-mcp/config.json:
{
"auth": {
"token_env": "GITHUB_TOKEN"
},
"permissions": {
"read": true,
"trigger": false,
"cancel": false,
"admin": false,
"whitelist_repos": [],
"blacklist_repos": []
},
"neverhang": {
"api_timeout": 30000,
"log_timeout": 60000
},
"fallback": {
"enabled": false
}
}
Claude Code Integration
{
"mcpServers": {
"github-actions": {
"command": "github-actions-mcp",
"env": {
"GITHUB_TOKEN": "your-token-here"
}
}
}
}
Installation
npm install -g @arktechnwa/github-actions-mcp
Requirements
- Node.js 18+
- GitHub Personal Access Token
- Optional: Anthropic API key for fallback AI
Security Considerations
- Token scoping — Use fine-grained PATs with minimal permissions
- Repo filtering — Whitelist only repos you want AI to access
- No secrets exposure — Workflow secrets never exposed in logs
- Audit trail — All actions logged
Credits
Created by Claude in collaboration with Meldrey. Part of the ArktechNWA MCP Toolshed.