Skip to main content
Glama
Isco0819

act-mcp

by Isco0819
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

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 bash

Related MCP server: AI Code Review MCP Server

MCP 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 fix

MCP 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 building

Environment variables

Variable

Default

Description

ACT_BIN

act

Path to the act binary (useful for testing)

Available Tools

3 tools
get_logsA

Return cached stdout+stderr from the most recent run_job call

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses caching and 'most recent' behavior, but lacks details like how long logs are cached, what happens if no run_job was called, or output format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short, front-loaded sentence with no wasted words. Every word adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, no output schema, and no annotations, the description is functional but leaves gaps: output format, error behavior, and caching duration. Adequate for a simple tool but not fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and schema coverage is 100% (empty schema). Baseline for zero parameters is 4, and the description correctly implies no parameters are needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns 'cached stdout+stderr from the most recent run_job call', with a specific verb and resource. It implicitly distinguishes from siblings: list_workflows lists workflows, run_job executes jobs.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool is used after run_job to retrieve logs, but provides no explicit guidance on when to use vs alternatives, or what happens if no prior run_job exists.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_workflowsA

List .github/workflows/*.yml files and their job names

ParametersJSON Schema
NameRequiredDescriptionDefault
cwdNoRepository root directory (defaults to process.cwd())

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description carries full behavioral burden. It discloses the read-only nature by using 'list', but lacks details about execution context, permissions, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence of ten words, front-loading the purpose with no extraneous content. Every word contributes meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low parameter count and no output schema, the description is mostly complete for a simple listing tool. Minor missing context about directory location and return format, but adequate overall.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% for the single parameter 'cwd'. The description adds no extra semantic value beyond what the schema already provides, meeting the baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'list' and resource '.github/workflows/*.yml files', and specifies the returned information ('job names'). It effectively distinguishes from sibling tools get_logs and run_job.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool versus alternatives is provided. The context is implied but no exclusions or when-not scenarios are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_jobA

Run a specific job via act -j , returns exitCode and captured logs

ParametersJSON Schema
NameRequiredDescriptionDefault
jobNameYesJob ID to run (must match a key under "jobs:" in the workflow YAML)
cwdNoRepository root directory (defaults to process.cwd())

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full behavioral disclosure. It mentions the action (run) and return values, but does not disclose side effects, permissions needed, or whether the execution modifies state.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence that immediately conveys the tool's purpose and outputs, with no filler or redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

While the description includes return type information (exitCode, captured logs) and references the underlying command, it could benefit from clarifying what 'act' is and any prerequisites for job names. Overall it is mostly complete for a simple execution tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema coverage is 100%, with both parameters described. The description adds minimal extra value by mentioning the 'act -j' command and specifying return values, but does not elaborate on parameter syntax or constraints beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool runs a specific job using 'act -j <jobName>' and specifies return values as exitCode and captured logs. It distinguishes from siblings (get_logs, list_workflows) by focusing on job execution.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Usage context is implied: the tool is for running jobs, while siblings retrieve logs or list workflows. However, there is no explicit guidance on when to prefer this tool over alternatives or any conditions for use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedget_logs
    • First observedlist_workflows
    • First observedrun_job
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool targets a distinct action: listing workflows, running a job, and retrieving logs. There is no functional overlap between them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern using snake_case: list_workflows, run_job, get_logs. No deviations.

Tool Count5/5

Three tools is within the typical well-scoped range (3-15) and each tool serves a necessary and clear purpose in the workflow.

Completeness5/5

The tool set covers the full lifecycle for the server's domain: listing available workflows, executing a job, and retrieving results. No obvious gaps are present.

Maintenance

ActivityStale
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • GitHub Actions MCP

    ArkTechNWA
    A
    license
    A
    quality
    Not graded
    maintenance
    Connects AI assistants to GitHub Actions workflows to monitor CI/CD pipelines, view run logs, diagnose failures, and optionally trigger or manage workflows with granular permission controls.
    10
    1
    -

  • AI Code Review MCP Server

    NamPH-Kozocom
    A
    license
    B
    quality
    D
    maintenance
    Integrates GitHub repository management and local file system access to enable AI agents to perform code reviews and manage pull requests. It provides tools for listing repositories, retrieving PR diffs, and searching or reading files within a specified workspace.
    7
    33 npm
    MIT

  • logicapps-mcp

    laveeshb
    A
    license
    A
    quality
    C
    maintenance
    Enables managing and debugging Azure Logic Apps through natural language, with tools for listing, debugging, creating, updating, and deleting workflows.
    40
    33 npm
    6
    MIT