内容
# GitHub Actions MCP 服务器
> 一个智能的 MCP（模型上下文协议）服务器，为 AI 代理提供对 GitHub Actions CI/CD 管道的完全控制权，包括实时监控、日志分析、AI 驱动的故障诊断和部署管理。
---
## 为什么存在
大多数 GitHub MCP 服务器允许 AI 代理读取文件、创建问题和管控拉取请求。<br>
**但它们无法触及您的 CI/CD 管道。**
| 功能 | 现有 GitHub MCP | 此服务器 |
|------------|:-------------------:|:-----------:|
| 列出工作流运行 | ❌ | ✅ |
| 获取执行日志 | ❌ | ✅ |
| 使用 AI 诊断故障 | ❌ | ✅ |
| 重运行 / 取消工作流 | ❌ | ✅ |
| 跟踪部署和回滚 | ❌ | ✅ |
| 实时监控仓库 | ❌ | ✅ |
该服务器填补了这一空白，使自主 DevOps 代理能够**监控、诊断和操作**您的管道，无需人工干预。
---
## 功能
- **13 个专门的 MCP 工具**，涵盖整个 CI/CD 生命周期
- **AI 驱动的故障分析** — 发送解析的日志到 Claude，返回根本原因 + 建议的修复 + 严重程度
- **实时管道监控** — 基于轮询的监视器，带有可配置的间隔
- **完全的工作流控制** — 重运行（所有作业或仅失败的作业），取消，监视直到完成
- **部署管理** — 列出环境，跟踪状态，触发回滚
- **工件处理** — 列出和获取预签名的下载 URL
- **安全设计** — 令牌从不记录或在响应中暴露
- **Docker 就绪** — 多阶段构建，用于生产部署
---
## 演示
询问 Claude（或任何 MCP 兼容的 AI 代理）：
```
"为什么我的 CI 管道在 main 分支上失败了？"
```
代理将自动：
1. 获取最新的失败工作流运行
2. 检索和解析执行日志
3. 将错误上下文发送到 Claude 进行分析
4. 返回结构化的诊断：
```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."
}
```
---
## 先决条件
- **Node.js** 20+
- **GitHub 个人访问令牌**，具有作用域：`repo`、`workflow`、`read:org`<br>
→ 在 [github.com/settings/tokens](https://github.com/settings/tokens) 处创建
- **Anthropic API 密钥**，用于 Claude 驱动的分析<br>
→ 在 [console.anthropic.com](https://console.anthropic.com) 处获取
---
## 快速入门
```bash
# 1. 克隆仓库
git clone https://github.com/muhammedehab35/GITOPS-MCP/tree/main
cd github-actions-mcp
# 2. 安装依赖
npm install
# 3. 配置环境
cp .env.example .env
# 在 .env 中填写 GITHUB_TOKEN 和 ANTHROPIC_API_KEY
# 4. 构建
npm run build
# 5. 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector node dist/index.js
```
---
## 连接到 Claude 桌面版
查找您的配置文件：
- **macOS**：`~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**：`%APPDATA%\Claude\claude_desktop_config.json`
添加此配置：
```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"
}
}
}
}
```
重启 Claude 桌面版。你将看到 🔨 工具图标 — 服务器已连接。
---
## 可用工具
### 仓库
| 工具 | 描述 |
|------|-------------|
| `github_list_repositories` | 列出所有可访问的仓库，包含语言、星星和可见性 |
### 工作流
| 工具 | 描述 |
|------|-------------|
| `github_list_workflows` | 列出仓库中定义的所有 GitHub Actions 工作流 |
| `github_list_workflow_runs` | 列出最近的运行记录，支持按状态、分支和计数筛选 |
| `github_get_workflow_run` | 获取运行记录的完整详细信息，包括所有作业状态和时间 |
| `github_watch_workflow` | 每 10 秒轮询运行记录，直到完成或 5 分钟超时 |
### 日志和
| 工具 | 描述 |
|------|-------------|
| `github_get_workflow_logs` | 获取和解析每个作业的日志，自动提取错误 |
| `github_analyze_failure` | **AI 诊断** — 通过 Claude 获取根本原因、修复建议、严重程度和诊断报告 |
### 操作
| 工具 | 描述 |
|------|-------------|
| `github_rerun_workflow` | 重运行工作流 — 所有作业或仅失败的作业 |
| `github_cancel_workflow` | 取消排队或正在进行的工作流 |
### 工件
| 工具 | 描述 |
|------|-------------|
| `github_download_artifacts` | 列出工件或获取特定工件的预签名下载 URL |
### 部署
| 工具 | 描述 |
|------|-------------|
| `github_get_deployments` | 列出环境的部署记录，附带最新状态 |
| `github_rollback_deployment` | 创建指向以前稳定引用的新部署 |
### 监控
| 工具 | 描述 |
|------|-------------|
| `github_monitor_repository` | 启动/停止仓库的连续轮询以获取工作流更改 |
---
## 环境变量
| 变量 | 必需 | 默认值 | 描述 |
|----------|:--------:|---------|-------------|
| `GITHUB_TOKEN` | ✅ | — | GitHub 个人访问令牌 (`repo`、`workflow`、`read:org`) |
| `ANTHROPIC_API_KEY` | ✅ | — | Anthropic API 密钥，用于 Claude 驱动的故障分析 |
| `POLLING_INTERVAL_MS` | ❌ | `30000` | `monitor_repository` 轮询 GitHub 的频率（毫秒） |
| `LOG_LEVEL` | ❌ | `info` | 日志详细程度：`debug` / `info` / `warn` / `error` |
---
## Docker
```bash
# 使用 Docker Compose 启动（自动读取 .env）
docker-compose up -d
# 或手动构建和运行
docker build -t github-actions-mcp .
docker run --env-file .env github-actions-mcp
```
---
## 开发
```bash
npm run dev # 使用 tsx 运行（无需构建步骤）
npm run build # 将 TypeScript 编译到 dist/
npm start # 运行编译后的输出
npm test # 运行所有测试（Vitest）
npm run typecheck # TypeScript 类型检查，无输出
```
### 运行测试
```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)
```
---
## 架构
```
src/
├── index.ts # FastMCP 服务器 — 连接所有 13 个工具
├── config/
│ └── env.ts # Zod 验证的环境配置
├── modules/
│ ├── auth/
│ │ └── github-auth.ts # GitHub PAT → Octokit 实例
│ ├── connector/
│ │ └── github-rest.ts # 所有 GitHub REST API 调用（Octokit）
│ ├── logs/
│ │ └── logs-analyzer.ts # 日志解析和错误模式检测
│ ├── ai/
│ │ └── ai-engine.ts # Claude API — 故障诊断
│ └── monitoring/
│ └── workflow-monitor.ts # 基于轮询的仓库监视器
└── 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
```
### `github_analyze_failure` 工作原理
```
代理调用 github_analyze_failure(owner, repo, runId)
│
├─► getWorkflowRun() → 确认结论 = "failure"
├─► getWorkflowRunJobs() → 确定失败的作业
├─► getJobLogs() × N → 获取原始日志文本
│
├─► LogsAnalyzer.parseWorkflowLogs() → 提取失败的步骤 + 错误
├─► LogsAnalyzer.extractErrorContext() → 获取周围的日志行
│
└─► AIEngine.analyzeFailure() → 发送到 Claude
│
└─► 返回：probableCause · suggestedFixes · severity · diagnosticReport
```
---
## 路线图
- [ ] 用于实时管道可视化的 Web 仪表盘
- [ ] 工作流事件的 Slack / Webhook 通知
- [ ] GitLab CI/CD 支持
- [ ] Azure DevOps 连接器
- [ ] 自愈管道（自动重运行，并带有 AI 建议的修复）
- [ ] 多仓库聚合仪表盘
---
## 贡献
欢迎提交拉取请求。对于重大更改，请先打开问题讨论您要更改的内容。
1. 分叉仓库
2. 创建功能分支 (`git checkout -b feat/amazing-feature`)
3. 提交更改 (`git commit -m 'feat: add amazing feature'`)
4. 推送到分支 (`git push origin feat/amazing-feature`)
5. 打开拉取请求
---
## 许可证
MIT — 请参阅 [LICENSE](LICENSE) 了解详细信息。
---
<p align="center">
使用 <a href="https://github.com/punkpeye/fastmcp">FastMCP</a> 构建 ·
由 muhammed ehab 为 GitHub 社区提供支持
</p>
