act-mcp
MCP stdio server exposing three tools for running GitHub Actions locally via act.
Peer dependency: act
act must be installed and in PATH:
# macOS
brew install act
# Linux
curl https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bashMCP Tools
list_workflows
Globs .github/workflows/*.yml and returns job names from each file.
| Field | Type | Description | |---|---|---| | cwd | string? | Repo root (default: process.cwd()) |
Returns: Array<{ file: string, jobs: string[] }>
run_job
Spawns act -j <jobName>, captures stdout+stderr, caches logs.
| Field | Type | Description | |---|---|---| | jobName | string | Job ID (key under jobs: in the YAML) | | cwd | string? | Repo root (default: process.cwd()) |
Returns: { exitCode: number, logs: string }
get_logs
Returns logs cached by the most recent run_job call.
Returns: { logs: string | null }
Agent loop
list_workflows → pick failing job
run_job → read exitCode + logs
get_logs → inspect failure output
(patch YAML)
run_job → verify fixMCP client config (Claude Desktop)
{
"mcpServers": {
"act-mcp": {
"command": "npx",
"args": ["act-mcp"]
}
}
}Or point cwd at a specific repo:
{
"mcpServers": {
"act-mcp": {
"command": "npx",
"args": ["act-mcp"],
"env": {}
}
}
}Pass cwd as a tool argument at call time:
{ "name": "list_workflows", "arguments": { "cwd": "/path/to/repo" } }Development
npm install
npm run build # tsc → dist/
npm test # vitest (uses mock act binary, no act required)
npm run dev # run via tsx without buildingEnvironment variables
| Variable | Default | Description | |---|---|---| | ACT_BIN | act | Path to the act binary (useful for testing) |
