NNTin/mcp-act

MCP Server with nektos/act

This project provides a Multi-Container Platform (MCP) server that includes nektos/act for running GitHub Actions workflows locally inside a Docker container. The MCP server can also spawn additional containers for workflow steps by connecting to the host Docker daemon.

Motivation

AI agents and other automated tools often encounter this problem:

"I couldn’t run the workflow here (no Docker access in this environment). Please re-run act."

Many environments, including typical AI execution contexts, don’t have Docker access, so act cannot execute GitHub Actions workflows.

This project solves that by:

1. Packaging act inside a dedicated MCP server container.
2. Giving the container controlled access to the host Docker daemon.
3. Exposing act as a tool that AI agents (or orchestrators) can use to run workflows safely and programmatically.

In other words, this MCP server turns act into an externally callable tool, enabling automated systems to execute workflows as part of larger AI pipelines.

Features

Current Implementation

• run_act - Run act <event> with optional -W workflow file, -j job, and limited extra CLI flags.
• act_version - Show the installed act version to confirm availability.

Prerequisites

• Docker Desktop with MCP Toolkit enabled
• Docker MCP CLI plugin (docker mcp command)
• Host Docker daemon available and mounted into the container (e.g., -v /var/run/docker.sock:/var/run/docker.sock)
• Mount your repository into the container so act can see workflows (e.g., -v /path/to/repo:/workspace)

Installation

See the numbered steps in the instructions section provided with these files.

Usage Examples

In Claude Desktop, you can ask:

• "Run act push on my repo using .github/workflows/ci.yml job tests"
• "Show the installed act version"

Example tool calls:

• 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

Architecture

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

Development

Local Testing

# (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

Adding New Tools

1. Add the function to mcp-act_server.py.
2. Decorate it with @mcp.tool().
3. Keep parameters as strings with empty defaults and single-line docstrings.
4. Rebuild the Docker image and update your catalog tool list.

Troubleshooting

Tools Not Appearing

• Verify Docker image built successfully.
• Check catalog and registry entries for typos.
• Ensure Claude Desktop config includes the custom catalog.
• Restart Claude Desktop after changes.

act Execution Issues

• Confirm Docker socket is mounted and the daemon is running.
• Ensure your repository is mounted at the path passed via workdir or MCP_ACT_WORKDIR.
• Use act_version to verify the binary is present inside the container.

Security Considerations

• No secrets required by default.
• Running as non-root user inside the container.
• Inputs are validated to limit dangerous shell characters and token counts.
• Command output is truncated to avoid oversized responses.