GitHub Actions MCP 服务器

用于 GitHub Actions API 的 MCP 服务器，使 AI 助手能够管理和操作 GitHub Actions 工作流。

特性

• 完整的工作流管理: 列出、查看、触发、取消和重新运行工作流
• 工作流运行分析: 获取关于工作流运行及其作业的详细信息
• 全面的错误处理: 带有增强细节的清晰错误消息
• 灵活的类型验证: 强大的类型检查，优雅地处理 API 变体
• 以安全为中心的设计: 超时处理、速率限制和严格的 URL 验证

工具

1. list_workflows

   • 列出 GitHub 仓库中的工作流
   • 输入:
     • owner (字符串): 仓库所有者 (用户名或组织)
     • repo (字符串): 仓库名称
     • page (可选 数字): 分页的页码
     • perPage (可选 数字): 每页的结果数 (最大 100)
   • 返回: 仓库中工作流的列表

2. get_workflow

   • 获取特定工作流的详细信息
   • 输入:
     • owner (字符串): 仓库所有者 (用户名或组织)
     • repo (字符串): 仓库名称
     • workflowId (字符串 或 数字): 工作流的 ID 或文件名
   • 返回: 关于工作流的详细信息

3. get_workflow_usage

   • 获取工作流的使用统计信息
   • 输入:
     • owner (字符串): 仓库所有者 (用户名或组织)
     • repo (字符串): 仓库名称
     • workflowId (字符串 或 数字): 工作流的 ID 或文件名
   • 返回: 使用统计信息，包括计费分钟数

4. list_workflow_runs

   • 列出仓库或特定工作流的所有工作流运行
   • 输入:
     • owner (字符串): 仓库所有者 (用户名或组织)
     • repo (字符串): 仓库名称
     • workflowId (可选 字符串 或 数字): 工作流的 ID 或文件名
     • actor (可选 字符串): 按触发工作流的用户过滤
     • branch (可选 字符串): 按分支过滤
     • event (可选 字符串): 按事件类型过滤
     • status (可选 字符串): 按状态过滤
     • created (可选 字符串): 按创建日期过滤 (YYYY-MM-DD)
     • excludePullRequests (可选 布尔值): 排除由 PR 触发的运行
     • checkSuiteId (可选 数字): 按 check suite ID 过滤
     • page (可选 数字): 分页的页码
     • perPage (可选 数字): 每页的结果数 (最大 100)
   • 返回: 符合条件的工作流运行列表

5. get_workflow_run

   • 获取特定工作流运行的详细信息
   • 输入:
     • owner (字符串): 仓库所有者 (用户名或组织)
     • repo (字符串): 仓库名称
     • runId (数字): 工作流运行的 ID
   • 返回: 关于特定工作流运行的详细信息

6. get_workflow_run_jobs

   • 获取特定工作流运行的作业
   • 输入:
     • owner (字符串): 仓库所有者 (用户名或组织)
     • repo (字符串): 仓库名称
     • runId (数字): 工作流运行的 ID
     • filter (可选 字符串): 按完成状态过滤作业 ('latest', 'all')
     • page (可选 数字): 分页的页码
     • perPage (可选 数字): 每页的结果数 (最大 100)
   • 返回: 工作流运行中的作业列表

7. trigger_workflow

   • 触发工作流运行
   • 输入:
     • owner (字符串): 仓库所有者 (用户名或组织)
     • repo (字符串): 仓库名称
     • workflowId (字符串 或 数字): 工作流的 ID 或文件名
     • ref (字符串): 运行工作流的引用 (分支、标签或 SHA)
     • inputs (可选 对象): 工作流的输入参数
   • 返回: 关于触发的工作流运行的信息

8. cancel_workflow_run

   • 取消工作流运行
   • 输入:
     • owner (字符串): 仓库所有者 (用户名或组织)
     • repo (字符串): 仓库名称
     • runId (数字): 工作流运行的 ID
   • 返回: 取消操作的状态

9. rerun_workflow

   • 重新运行工作流运行
   • 输入:
     • owner (字符串): 仓库所有者 (用户名或组织)
     • repo (字符串): 仓库名称
     • runId (数字): 工作流运行的 ID
   • 返回: 重新运行操作的状态

与 Claude Desktop 一起使用

首先，确保您已构建项目 (请参阅下面的构建部分)。然后，将以下内容添加到您的 claude_desktop_config.json：

{
  "mcpServers": {
    "github-actions": {
      "command": "node",
      "args": [
        "<path-to-mcp-server>/dist/index.js"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

构建

克隆仓库并构建：

git clone https://github.com/ko1ynnky/github-actions-mcp-server.git
cd github-actions-mcp-server
npm install
npm run build

这将在 dist 目录中创建运行 MCP 服务器所需的必要文件。

使用示例

列出仓库中的工作流：

const result = await listWorkflows({
  owner: "your-username",
  repo: "your-repository"
});

触发工作流：

const result = await triggerWorkflow({
  owner: "your-username",
  repo: "your-repository",
  workflowId: "ci.yml",
  ref: "main",
  inputs: {
    environment: "production"
  }
});

故障排除

常见问题

1. 身份验证错误:

   • 确保您的 GitHub 令牌具有正确的权限
   • 检查令牌是否已正确设置为环境变量

2. 速率限制:

   • 服务器实施速率限制以避免达到 GitHub API 限制
   • 如果您遇到速率限制错误，请降低请求的频率

3. 类型验证错误:

   • GitHub API 响应有时可能与预期模式不同
   • 服务器实施灵活的验证来处理大多数变体
   • 如果您遇到持续性错误，请提出 issue

许可证

此 MCP 服务器在 MIT 许可证下获得许可。