GitHub Actions MCP Server

An intelligent MCP (Model Context Protocol) server that gives AI agents full control over GitHub Actions CI/CD pipelines — including real-time monitoring, log analysis, AI-powered failure diagnosis, and deployment management.

---

Why This Exists

Most GitHub MCP servers let AI agents read files, create issues, and manage pull requests.
But they can't touch your CI/CD pipelines.

Capability	Existing GitHub MCPs	This Server
List workflow runs	❌	✅
Fetch execution logs	❌	✅
Diagnose failures with AI	❌	✅
Rerun / cancel workflows	❌	✅
Track deployments & rollback	❌	✅
Monitor repos in real time	❌	✅

This server closes that gap — enabling autonomous DevOps agents that can monitor, diagnose, and act on your pipelines without human intervention.

---

Features

• 13 purpose-built MCP tools covering the full CI/CD lifecycle
• AI-powered failure analysis — sends parsed logs to Claude, returns root cause + suggested fixes + severity
• Real-time pipeline monitoring — polling-based watcher with configurable interval
• Full workflow control — rerun (all or failed jobs only), cancel, watch until completion
• Deployment management — list environments, track statuses, trigger rollbacks
• Artifact handling — list and get pre-signed download URLs
• Secure by design — tokens never logged or exposed in responses
• Docker-ready — multi-stage build for production deployment

---

Demo

Ask Claude (or any MCP-compatible AI agent):

"Why did my CI pipeline fail on the main branch?"

The agent will automatically:

1. Fetch the latest failed workflow run
2. Retrieve and parse the execution logs
3. Send the error context to Claude for analysis
4. Return a structured diagnosis:

{
  "probableCause": "npm peer dependency conflict between react@18 and testing-library@13",
  "suggestedFixes": [
    "Add --legacy-peer-deps to your npm install command",
    "Upgrade @testing-library/react to v14",
    "Pin react to v17 until dependencies are resolved"
  ],
  "severity": "high",
  "diagnosticReport": "The build failed during dependency installation due to an unresolvable peer conflict introduced in the last commit. This is a common issue when mixing React 18 with older testing utilities."
}

---

Prerequisites

• Node.js 20+
• GitHub Personal Access Token with scopes: repo, workflow, read:org
  → Create at github.com/settings/tokens
• Anthropic API Key for Claude-powered analysis
  → Get at console.anthropic.com

---

Quick Start

# 1. Clone the repository
git clone https://github.com/muhammedehab35/GITOPS-MCP/tree/main
cd github-actions-mcp

# 2. Install dependencies
npm install

# 3. Configure environment
cp .env.example .env
# Fill in GITHUB_TOKEN and ANTHROPIC_API_KEY in .env

# 4. Build
npm run build

# 5. Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

---

Connect to Claude Desktop

Find your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add this configuration:

{
  "mcpServers": {
    "github": {
      "command": "node",
      "args": ["/absolute/path/to/github-actions-mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "ANTHROPIC_API_KEY": "sk-ant-your_key_here",
        "POLLING_INTERVAL_MS": "30000",
        "LOG_LEVEL": "info"
      }
    }
  }
}

Restart Claude Desktop. You'll see the 🔨 tools icon — the server is connected.

---

Available Tools

Repositories

Tool	Description
github_list_repositories	List all repositories accessible with your token, with language, stars, and visibility

Workflows

Tool	Description
github_list_workflows	List all GitHub Actions workflows defined in a repository
github_list_workflow_runs	List recent runs with filters for status, branch, and count
github_get_workflow_run	Get full details of a run including all job statuses and timing
github_watch_workflow	Poll a run every 10s until completion or 5-minute timeout

Logs & Analysis

Tool	Description
github_get_workflow_logs	Fetch and parse per-job logs with automatic error extraction
github_analyze_failure	AI diagnosis — root cause, fixes, severity, and diagnostic report via Claude

Actions

Tool	Description
github_rerun_workflow	Rerun a workflow — all jobs or failed jobs only
github_cancel_workflow	Cancel a workflow that is queued or in progress

Artifacts

Tool	Description
github_download_artifacts	List artifacts or get a pre-signed download URL for a specific one

Deployments

Tool	Description
github_get_deployments	List deployments by environment with latest status
github_rollback_deployment	Create a new deployment pointing to a previous stable ref

Monitoring

Tool	Description
github_monitor_repository	Start / stop continuous polling of a repo for workflow changes

---

Environment Variables

Variable	Required	Default	Description
GITHUB_TOKEN	✅	—	GitHub Personal Access Token (repo, workflow, read:org)
ANTHROPIC_API_KEY	✅	—	Anthropic API key for Claude-powered failure analysis
POLLING_INTERVAL_MS	❌	30000	How often monitor_repository polls GitHub (milliseconds)
LOG_LEVEL	❌	info	Log verbosity: debug / info / warn / error

---

Docker

# Start with Docker Compose (reads from .env automatically)
docker-compose up -d

# Or build and run manually
docker build -t github-actions-mcp .
docker run --env-file .env github-actions-mcp

---

Development

npm run dev        # Run with tsx (no build step needed)
npm run build      # Compile TypeScript to dist/
npm start          # Run compiled output
npm test           # Run all tests (Vitest)
npm run typecheck  # TypeScript type check without emitting

Running Tests

npm test

✓ tests/modules/logs-analyzer.test.ts   (5 tests)
✓ tests/modules/ai-engine.test.ts       (2 tests)
✓ tests/tools/repositories.test.ts      (2 tests)
✓ tests/tools/workflows.test.ts         (3 tests)

Test Files  4 passed (4)
Tests       12 passed (12)

---

Architecture

src/
├── index.ts                          # FastMCP server — wires all 13 tools
├── config/
│   └── env.ts                        # Zod-validated environment config
├── modules/
│   ├── auth/
│   │   └── github-auth.ts            # GitHub PAT → Octokit instance
│   ├── connector/
│   │   └── github-rest.ts            # All GitHub REST API calls (Octokit)
│   ├── logs/
│   │   └── logs-analyzer.ts          # Log parsing & error pattern detection
│   ├── ai/
│   │   └── ai-engine.ts              # Claude API — failure diagnosis
│   └── monitoring/
│       └── workflow-monitor.ts       # Polling-based repo watcher
└── tools/
    ├── repositories.ts               # github_list_repositories
    ├── workflows.ts                  # github_list_workflows, list_runs, get_run
    ├── watcher.ts                    # github_watch_workflow
    ├── logs.ts                       # github_get_workflow_logs, analyze_failure
    ├── actions.ts                    # github_rerun_workflow, cancel_workflow
    ├── artifacts.ts                  # github_download_artifacts
    ├── deployments.ts                # github_get_deployments, rollback_deployment
    └── monitor.ts                    # github_monitor_repository

How github_analyze_failure works

Agent calls github_analyze_failure(owner, repo, runId)
        │
        ├─► getWorkflowRun()        → confirm conclusion = "failure"
        ├─► getWorkflowRunJobs()    → identify failed jobs
        ├─► getJobLogs() × N        → fetch raw log text
        │
        ├─► LogsAnalyzer.parseWorkflowLogs()     → extract failed steps + errors
        ├─► LogsAnalyzer.extractErrorContext()   → get surrounding log lines
        │
        └─► AIEngine.analyzeFailure()            → send to Claude
                │
                └─► Returns: probableCause · suggestedFixes · severity · diagnosticReport

---

Roadmap

• [ ] Web dashboard for real-time pipeline visualization
• [ ] Slack / webhook notifications on workflow events
• [ ] GitLab CI/CD support
• [ ] Azure DevOps connector
• [ ] Self-healing pipelines (auto-rerun with AI-suggested fixes)
• [ ] Multi-repository aggregated dashboard

---

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you'd like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feat/amazing-feature)
5. Open a Pull Request

---

License

MIT — see LICENSE for details.

---

<p align="center"> Built with <a href="https://github.com/punkpeye/fastmcp">FastMCP</a> · Powered by muhammed ehab for github community </p>