GitHub Actions MCP 服务器

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

特性

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

工具

1. list_workflows

   • List workflows in a GitHub repository
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • page (optional number): Page number for pagination
     • perPage (optional number): Results per page (max 100)
   • Returns: List of workflows in the repository

2. get_workflow

   • Get details of a specific workflow
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • workflowId (string or number): The ID of the workflow or filename
   • Returns: Detailed information about the workflow

3. get_workflow_usage

   • Get usage statistics of a workflow
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • workflowId (string or number): The ID of the workflow or filename
   • Returns: Usage statistics including billable minutes

4. list_workflow_runs

   • List all workflow runs for a repository or a specific workflow
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • workflowId (optional string or number): The ID of the workflow or filename
     • actor (optional string): Filter by user who triggered the workflow
     • branch (optional string): Filter by branch
     • event (optional string): Filter by event type
     • status (optional string): Filter by status
     • created (optional string): Filter by creation date (YYYY-MM-DD)
     • excludePullRequests (optional boolean): Exclude PR-triggered runs
     • checkSuiteId (optional number): Filter by check suite ID
     • page (optional number): Page number for pagination
     • perPage (optional number): Results per page (max 100)
   • Returns: List of workflow runs matching the criteria

5. get_workflow_run

   • Get details of a specific workflow run
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • runId (number): The ID of the workflow run
   • Returns: Detailed information about the specific workflow run

6. get_workflow_run_jobs

   • Get jobs for a specific workflow run
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • runId (number): The ID of the workflow run
     • filter (optional string): Filter jobs by completion status ('latest', 'all')
     • page (optional number): Page number for pagination
     • perPage (optional number): Results per page (max 100)
   • Returns: List of jobs in the workflow run

7. trigger_workflow

   • Trigger a workflow run
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • workflowId (string or number): The ID of the workflow or filename
     • ref (string): The reference to run the workflow on (branch, tag, or SHA)
     • inputs (optional object): Input parameters for the workflow
   • Returns: Information about the triggered workflow run

8. cancel_workflow_run

   • Cancel a workflow run
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • runId (number): The ID of the workflow run
   • Returns: Status of the cancellation operation

9. rerun_workflow

   • Re-run a workflow run
   • Inputs:
     • owner (string): Repository owner (username or organization)
     • repo (string): Repository name
     • runId (number): The ID of the workflow run
   • Returns: Status of the re-run operation

与 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 的响应有时可能与预期模式不同
   • 服务器实现了灵活的验证来处理大多数变体
   • 如果遇到持续的错误，请提出问题

许可证

此 MCP 服务器根据 MIT 许可证发布。