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

{
  "permissions": {
    "read": true,
    "trigger": false,
    "cancel": false,
    "admin": false,

    "whitelist_repos": [
      "ArktechNWA/*",
      "myorg/myapp"
    ],

    "blacklist_repos": [
      "*/infrastructure",
      "*/secrets-*"
    ]
  }
}

github-actions-mcp --bypass-permissions

# Environment variable
export GITHUB_TOKEN=ghp_xxxxxxxxxxxx

# Or in config
{
  "auth": {
    "token_env": "GITHUB_TOKEN"
  }
}

gha_list_workflows({
  repo: string,           // "owner/repo"
  state?: "active" | "disabled" | "all"
})

gha_get_workflow({
  repo: string,
  workflow: string | number  // workflow file name or ID
})

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
})

{
  "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({
  repo: string,
  run_id: number,
  include_jobs?: boolean    // default: true
})

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
})

gha_trigger_workflow({
  repo: string,
  workflow: string,         // workflow file name
  ref: string,              // branch or tag
  inputs?: Record<string, string>  // workflow inputs
})

gha_rerun_workflow({
  repo: string,
  run_id: number,
  failed_only?: boolean     // only re-run failed jobs
})

gha_cancel_run({
  repo: string,
  run_id: number
})

gha_set_workflow_state({
  repo: string,
  workflow: string,
  enabled: boolean
})

gha_diagnose_failure({
  repo: string,
  run_id: number,
  use_ai?: boolean          // use Haiku for synthesis
})

{
  "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"
  }
}

{
  "rate_limit": {
    "remaining": 4892,
    "reset_at": "2025-12-29T11:00:00Z"
  }
}

{
  "fallback": {
    "enabled": true,
    "model": "claude-haiku-4-5",
    "api_key_env": "GHA_MCP_FALLBACK_KEY",
    "max_log_lines": 500,
    "max_tokens": 500
  }
}

{
  "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
  }
}

{
  "mcpServers": {
    "github-actions": {
      "command": "github-actions-mcp",
      "env": {
        "GITHUB_TOKEN": "your-token-here"
      }
    }
  }
}

npm install -g @arktechnwa/github-actions-mcp