process-runner-mcp

An MCP server for managing long-running development processes. Start, stop, restart, and monitor shell processes (e.g. npm run dev, cargo watch) from an AI assistant via the Model Context Protocol — so the assistant remembers the processes it starts and can check in on them at any time.

Features

• 5 MCP tools: start_process, stop_process, restart_process, list_processes, read_logs
• Web UI: browser-based log viewer with live streaming at http://localhost:3834
• CLI: list, logs (with --follow), and stop subcommands
• Session recovery: re-adopts still-running processes after a server restart
• Safe process teardown: kills the entire process group tree, not just the parent PID
• Durable log storage: in-memory ring buffer + per-process log files + SQLite

Installation

cargo install --path .

Or build manually:

cargo build --release
# binary at: ./target/release/process-runner-mcp

MCP Client Setup

The server communicates over stdio (JSON-RPC). Register it with your AI client:

OpenCode (~/.config/opencode/config.json):

{
  "mcp": {
    "process-runner": {
      "type": "local",
      "command": "process-runner-mcp",
      "args": []
    }
  }
}

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "process-runner": {
      "command": "process-runner-mcp",
      "args": []
    }
  }
}

CLI Usage

These subcommands connect to a running server instance:

# List all managed processes
process-runner-mcp list

# Show last 100 log lines for a process
process-runner-mcp logs <name>

# Show last N lines
process-runner-mcp logs <name> -n 50

# Follow live log output (like tail -f)
process-runner-mcp logs <name> --follow

# Stop a process
process-runner-mcp stop <name>

Web UI

While the server is running, open http://localhost:3834 for a browser-based log viewer with live SSE streaming.

Configuration

Option	Flag	Environment variable	Default
HTTP port	--port <PORT>	PROCESS_RUNNER_PORT	3834

process-runner-mcp serve --port 4000
# or
PROCESS_RUNNER_PORT=4000 process-runner-mcp

Runtime Data

All runtime data is stored under $XDG_RUNTIME_DIR/process-runner-mcp/ (falls back to /tmp/process-runner-mcp/):

process-runner-mcp/
├── server.json            # port + PID (used by CLI for discovery)
├── server.log             # server diagnostic log
├── process-runner.db      # SQLite database (WAL mode)
└── logs/
    └── <process-name>/
        ├── stdout.log
        └── stderr.log