gh-actions-mcp

关键词

GitHub Actions工作流管理日志检索API 服务JSON-RPC

项目简介

gh-actions-mcp 是一个以 MCP 协议实现的服务器端应用，专注提供对 GitHub Actions 的上下文信息、执行工具以及提示模板等能力。通过 MCP 客户端发起的 JSON-RPC 请求，服务器返回资源数据、执行工具调用结果以及渲染好的提示模板，帮助大语言模型在与 GitHub Actions 的集成场景中获取所需信息并执行外部操作。

主要功能点

  • 列出仓库中所有工作流（list_workflows）
  • 列出指定工作流的运行历史（list_runs）
  • 获取单个工作流运行的详情、日志、作业等（get_run、get_run_jobs、get_run_logs、get_log_files、get_artifact 等）
  • 触发、取消、重试工作流运行（trigger_workflow、cancel_workflow_run、rerun_workflow、wait_for_run 等）
  • 检索并过滤工作流日志（get_workflow_logs、get_log_section、list_log_sections 等）
  • 获取和下载工作流产物和工件内容（get_artifact、download_artifact、get_artifact_content 等）
  • 查询并汇总 Check Runs、等待 Check 完成等（get_check_status、wait_for_commit_checks 等）
  • 任务与运行的状态等待、并发控制和输出格式化（compact/plain 与 full/pretty 输出）

注意：该服务器以 MCP 框架提供后端能力，内部通过 GitHub API 与仓库数据进行交互，并对外暴露符合 MCP 的工具和参数结构，客户端通过 JSON-RPC 与其通信。

安装步骤

  • 构建与安装
    • 运行构建命令以生成可执行文件
    • 使用安装命令将构建产物安装到系统路径
  • 依赖准备
    • 需要 Go 环境（如 Go 1.20 及以上）
    • 需要 GitHub Token，具备访问目标仓库的权限（最常见做法：通过 GITHUB_TOKEN 环境变量或 --token 参数提供；在 macOS 上也支持通过 keychain 获取令牌）
  • 令牌获取方式
    • 直接通过命令行参数 --token 提供
    • 或设置环境变量 GITHUB_TOKEN/GH_TOKEN
    • 或在 macOS 上通过 gh auth login 自动获取（需要 GH CLI 配置）

服务器配置（JSON，供 MCP 客户端使用）

说明：MCP 客户端需要知道服务器的启动命令及参数，以下为示例配置，实际使用请将占位符替换为你的环境信息。配置中包含服务器名称、启动命令及默认参数，便于快速接入 MCP 客户端。

{ "server_name": "gh-actions", "command": "/path/to/gh-actions-mcp", "args": [ "--repo-owner", "<your_owner>", "--repo-name", "<your_repo>", "--token", "<your_github_token>" ], "notes": "token 可以通过 GITHUB_TOKEN 环境变量注入，或通过 gh auth login 使用系统钥匙串获取。若使用 macOS，请确保 gh CLI 已登录以支持钥匙串集成。" }

参数说明

  • server_name: MCP 客户端在 UI 或日志中显示的服务器名称，应与实际部署的一致
  • command: 服务器执行文件的实际路径
  • args: 启动时需要的参数，包含仓库拥有者、仓库名称以及访问令牌
  • 备注/注释: 说明 token 的获取方式和安全性

基本使用方法

  • 启动方式
    • 使用标注的命令行参数启动 gh-actions-mcp 服务，传入目标仓库信息与认证信息
  • 运行模式
    • 服务器默认通过 Stdio 提供 MCP 能力，适配 Claude Desktop 等客户端
    • 也可根据需要调整传输模式和端口（如 SSE、HTTP 等，需在代码中相应修改或使用此仓库提供的扩展选项）
  • 与 MCP 客户端对接
    • MCP 客户端通过 JSON-RPC 发起对上述工具的调用，如 list_workflows、get_run、wait_for_run 等
    • 客户端会接收结构化的 JSON 结果或文本结果，方便在对话系统中呈现
  • 运行前的准备
    • 确保本地或远程 GitHub 令牌可用
    • 确保仓库 OWNER、REPO 名字正确无误，否则会在 API 调用阶段返回鉴权或资源定位相关错误

服务器信息

访问项目