Log inSubmit server
Runner MCP logo

Runner MCP

Self-hosted MCP boundary for approved project inspection, test runs, and controlled staging actions without arbitrary shell access.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget

Install Runner MCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "runner-mcp": {
      "command": "uvx",
      "args": [
        "aifordable-runner-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

The install command installed and started the server, which then stopped for configuration (such as an API key) that our sandbox does not have — expected for servers that connect to your account.

uvx aifordable-runner-mcp

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked .

Overview

Runner MCP provides an authenticated, self-hosted boundary for AI-assisted development and staging on an operator-managed host. It exposes locally configured projects, named actions, test profiles, and controlled operations instead of accepting arbitrary commands, executables, paths, or service names. Read-only work is broader, while mutating staging actions can require short-lived approval; production mutations remain disabled. Reach for it when an agent needs to verify real project changes without receiving a general-purpose remote shell.

Use cases

  • Run approved test suites after an AI-generated code change
  • Inspect files in configured development projects
  • Check or update selected staging operations
  • Hand off a bounded repository workflow to Runner Fabric
  • Stop execution through an operator-controlled emergency switch

Key features

  • Allow-listed project and action configuration
  • Predefined test profiles
  • Bounded output and approval gates
  • Loopback-first private connectivity
  • Optional GitHub mailbox transport
  • Optional Runner Fabric work-unit bridge

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked

Recent health check succeeded.

8/8 checks healthy over the last 32d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 16d ago via OSV.dev · aifordable-runner-mcp (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

Last commit2d agoMost recent push to the default branch.
Install checkRunsOur sandbox started it; it then asked for an API key or config.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Runner MCP works

What Runner MCP does

Runner MCP lets an AI client inspect configured projects, run predefined tests, and perform selected staging operations on a host controlled by the operator. The operator defines which projects and named actions exist; the client chooses among those bounded capabilities rather than submitting arbitrary shell commands or infrastructure values.

The service is intended for routine AI-assisted development and staging work, such as checking a safe file, verifying a change against a known test suite, or checking a staging service. It is a narrower execution boundary than SSH or a broad remote-control tool, and it is not intended to be a general-purpose maintenance interface.

How it works

An AI client connects through a private MCP transport to Runner MCP, which dispatches requests to configured projects, predefined test profiles, and approved staging operations. A human operator retains approval and emergency-stop controls. The authority model is asymmetric: inspection is easier to permit, mutating staging actions are more restricted, and higher-risk actions can require short-lived local approval.

An optional GitHub mailbox transport can carry bounded requests, but it does not turn GitHub into a channel for arbitrary shell commands. When Runner MCP and Runner Fabric share a host, an optional loopback-only bridge can hand off a bounded Fabric work-unit through coarse run, inspect, and cancel operations. The bridge is disabled by default and does not expand Runner MCP's authority.

Setup and configuration

The documented persistent installation uses Python 3.12 or newer and the uv tool manager:

bash
uv tool install aifordable-runner-mcp
runner-mcp setup
runner-mcp doctor
runner-mcp guide
runner-mcp status

For short-lived evaluation, the package can be invoked with uvx. Installation from source is also supported through the repository's install.sh script. runner-mcp setup configures the local service, while doctor, guide, and status help check its state and connectivity.

Connectivity is loopback-first. Public mode records an external HTTPS resource and authentication identity, but does not bind a public address, configure TLS, alter DNS or firewalls, install a reverse proxy, or create a tunnel. Operators can use Secure MCP Tunnel for supported OpenAI products or manage an HTTPS reverse proxy separately. A local operator wrapper is available when the service account and interactive operator account differ.

Tools and capabilities

  • Inspect files and other work within configured projects.
  • Run named test suites and predefined test profiles.
  • Perform explicitly configured staging operations.
  • Apply bounded output and allow-list controls around execution.
  • Use emergency-stop controls for the execution boundary.
  • Optionally run, inspect, or cancel a bounded Runner Fabric work-unit through the loopback bridge.
  • Optionally process bounded requests through a GitHub mailbox transport.

Limitations and notes

Runner MCP is in alpha and maintenance mode, with future work focused on security fixes, bugs, compatibility, and concrete operational needs. It is not a sandbox for untrusted code and does not replace every operator maintenance tool. Production mutations are disabled, and the optional Fabric bridge is not a second orchestration or control plane.

The service deliberately avoids unrestricted shell access. Its safety depends on the projects, actions, profiles, approvals, and host permissions configured by the operator. Dependency, build, or interpreter contract changes are not handled by self-update and require a local bootstrap or manual upgrade.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Runner MCP

Runner MCP is an MCP server that connects AI clients to operator-configured projects, predefined test profiles, and controlled staging operations. Its main tools support bounded inspection, test execution, staging actions, and optional Runner Fabric work-unit run, inspect, and cancel requests without exposing a general-purpose remote shell.

Install it persistently with `uv tool install aifordable-runner-mcp`, then run `runner-mcp setup`, `runner-mcp doctor`, `runner-mcp guide`, and `runner-mcp status`. You can also use `uvx` for short-lived evaluation or install directly from source with the repository's `install.sh` script.

No, Runner MCP intentionally does not use arbitrary shell commands as its normal interface. Operators configure projects, named actions, and test profiles, and the AI selects from those bounded capabilities instead of supplying commands, executable paths, filesystem paths, or service names.

Yes, Runner MCP can optionally connect to Runner Fabric through a loopback-only bridge when both products run on the same host. The bridge exposes bounded run, inspect, and cancel operations for a Fabric work-unit, is disabled by default, and does not expand Runner MCP's authority.

Yes, Runner MCP supports a private first-party ChatGPT/Codex control path. The package reuses the existing MCP boundary without embedding bearer-token values or adding another control plane. Supported OpenAI products can also use Secure MCP Tunnel for private access.

Related MCP servers

All in Developer Tools All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewRunner MCP AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/runner-mcp?style=directory)](https://allmcps.com/mcp/runner-mcp)
HTML Embed
<a href="https://allmcps.com/mcp/runner-mcp"><img src="https://allmcps.com/api/badge/runner-mcp?style=directory" alt="Runner MCP on AllMCPs" /></a>