# Runner MCP [Verified owner] [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/Blacksp1d3r/runner-mcp  
**GitHub Stars:** 0  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/runner-mcp

## Description
Self-hosted MCP for controlled AI development and staging without a general-purpose remote shell.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "runner-mcp": {
    "command": "uvx",
    "args": ["aifordable-runner-mcp"]
  }
}
```

## Documentation

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

_Full upstream README: https://allmcps.com/mcp/runner-mcp/readme_