AI导哈

GitHub Actions本地运行服务

提供基于Docker容器的GitHub Actions本地运行平台，支持通过MCP服务器安全调用act工具执行工作流。

  • by NNTin
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 NNTin/mcp-act

使用说明

MCP服务器与游泳/行动

该项目提供了 多容器平台（MCP）服务器 这包括 游泳运动员/表演 用于在Docker容器内本地运行GitHub Actions工作流。MCP服务器还可以通过连接到主机Docker守护进程为工作流步骤生成额外的容器。

动机

人工智能代理和其他自动化工具经常遇到这个问题：

“我无法在此处运行工作流（此环境中没有Docker访问权限）。请重新运行act。”

许多环境，包括典型的AI执行环境， 没有Docker访问权限，所以 act 无法执行GitHub操作工作流。

该项目通过以下方式解决了这一问题：

  1. 包装 act 在专用的MCP服务器容器内。
  2. 给容器 对主机Docker守护进程的受控访问.
  3. 暴露 act 作为人工智能代理（或编排者）可以用来安全地以编程方式运行工作流的工具。

换句话说，这个MCP服务器 回合 act 转化为可外部调用的工具，使自动化系统能够执行工作流，作为更大的人工智能管道的一部分。

特性

当前实施情况

  • run_act -快跑 act <event> 可选 -W 工作流文件， -j 作业和有限的额外CLI标志。
  • act_version -显示已安装 act 版本以确认可用性。

先决条件

  • 启用MCP工具包的Docker桌面
  • Docker MCP CLI插件(docker mcp 命令）
  • 主机Docker守护进程可用并安装到容器中（例如。， -v /var/run/docker.sock:/var/run/docker.sock)
  • 将您的存储库装入容器中，以便 act 可以看到工作流（例如。， -v /path/to/repo:/workspace)

安装

请参阅随这些文件提供的说明部分中的编号步骤。

使用示例

在Claude Desktop中，您可以问：

  • “使用.github/works/ci.yml作业测试在我的仓库上运行act push”
  • “显示已安装的act版本”

工具调用示例：

  • run_act event="push" workflow_path=".github/workflows/ci.yml" job="tests" workdir="/workspace"
  • run_act event="pull_request" workdir="/workspace" extra_args="--reuse"
  • act_version

建筑

Claude/Codex/Gemini/... → MCP Gateway → mcp-act MCP Server → nektos/act → Host Docker Daemon → Workflow containers
↓
Docker Desktop Secrets (none required)

sequenceDiagram
    autonumber
    participant User
    participant MCP_Server as MCP Server (with act)
    participant Docker_Daemon as Host Docker Daemon
    participant Workflow_Container as Workflow Step Container

    note over MCP_Server: Setup before running:\n- Mount Docker socket: /var/run/docker.sock:/var/run/docker.sock\n- Mount workspace: /path/to/repo:/github/workspace

    User->>MCP_Server: Request to run GitHub Actions workflow
    MCP_Server->>MCP_Server: Execute act with workflow
    MCP_Server->>Docker_Daemon: Request to create container for workflow step
    Docker_Daemon->>Workflow_Container: Start container
    Workflow_Container-->>Docker_Daemon: Step execution result/logs
    Docker_Daemon-->>MCP_Server: Return workflow step results
    MCP_Server-->>User: Return full workflow logs/results

发展

局部测试

# (optional) set where your repo is mounted inside the container
export MCP_ACT_WORKDIR="/workspace"

# Run directly (stdio transport)
python3 mcp-act_server.py

# Quick protocol probe
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python3 mcp-act_server.py

添加新工具

  1. 将该功能添加到 mcp-act_server.py.
  2. 用 @mcp.tool().
  3. 将参数保留为默认值为空的字符串和单行文档字符串。
  4. 重建Docker镜像并更新目录工具列表。

故障排除

工具未出现

  • 验证Docker镜像构建成功。
  • 检查目录和注册表项是否有拼写错误。
  • 确保Claude Desktop配置包含自定义目录。
  • 更改后重新启动Claude Desktop。

行动执行问题

  • 确认Docker套接字已挂载，守护进程正在运行。
  • 确保您的存储库已装载在通过传递的路径上 workdir 或 MCP_ACT_WORKDIR.
  • 使用 act_version 验证容器内是否存在二进制文件。

安全注意事项

  • 默认情况下不需要任何机密。
  • 在容器内以非root用户身份运行。
  • 对输入进行验证，以限制危险的shell字符和令牌计数。
  • 命令输出被截断以避免响应过大。

相关 MCP