Content
# 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:
```json
{
"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](https://github.com/settings/tokens)
- **Anthropic API Key** for Claude-powered analysis
→ Get at [console.anthropic.com](https://console.anthropic.com)
---
## Quick Start
```bash
# 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:
```json
{
"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
```bash
# 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
```bash
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
```bash
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](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>
