GitHub Actions MCP服务器

⚠️ 存档通知: 本仓库即将存档，因为官方GitHub MCP服务器正在添加Actions支持。详情见github/github-mcp-server#491。

用于GitHub Actions API的MCP服务器，使AI助手能够管理和操作GitHub Actions工作流。兼容多种AI编码助手，包括Claude Desktop、Codeium和Windsurf。

功能

• 完整的流程管理: 列出、查看、触发、取消和重新运行工作流
• 工作流运行分析: 获取工作流运行及其任务的详细信息
• 全面的错误处理: 提供清晰且详细的错误消息
• 灵活的类型验证: 强大的类型检查并优雅地处理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 (可选数字): 过滤检查套件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
   • 返回值: 重新运行操作的状态

与AI编码助手的使用

此MCP服务器兼容多种AI编码助手，包括Claude Desktop、Codeium和Windsurf。

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

Codeium

在您的Codeium MCP配置文件中添加以下配置（通常位于Unix系统上的~/.codeium/windsurf/mcp_config.json或Windows上的%USERPROFILE%\.codeium\windsurf\mcp_config.json）：

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

Windsurf

Windsurf使用与Codeium相同的配置格式。按照上述Codeium的方式添加服务器到您的Windsurf MCP配置中。

构建

Unix/Linux/macOS

克隆仓库并构建：

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

Windows

对于Windows系统，请使用特定于Windows的构建命令：

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

或者，您可以使用包含的批处理文件：

run-server.bat [可选-github-token]

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

Windows特定说明

前提条件

• Node.js（v14或更高版本）
• npm（v6或更高版本）

在Windows上运行服务器

1. 使用批处理文件（最简单的方法）：

   run-server.bat [可选-github-token]
   

   这将检查是否存在构建，如果需要则进行构建，并启动服务器。

2. 直接使用npm：

   npm run start
   

在Windows上设置GitHub个人访问令牌

为了实现全部功能并避免速率限制，您需要设置您的GitHub个人访问令牌。

选项：

1. 将其作为参数传递给批处理文件：

   run-server.bat your_github_token_here
   

2. 设置为环境变量：

   set GITHUB_PERSONAL_ACCESS_TOKEN=your_github_token_here
   npm run start
   

解决Windows问题

如果您遇到问题：

1. 构建错误: 确保正确安装了TypeScript。

   npm install -g typescript
   

2. 权限问题: 确保您在具有适当权限的命令提示符中运行命令。

3. Node.js错误: 验证您使用的Node.js版本是否兼容。

   node --version
   

使用示例

列出仓库中的工作流：

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许可发布。