delegate_runner

MCP Server for delegated command execution — run shell commands asynchronously and retrieve output on demand.

Installation

From PyPI (recommended)

uvx delegate-runner

From GitHub

uvx --from git+https://github.com/uppet/delegate_runner delegate-runner

Development install

git clone https://github.com/uppet/delegate_runner
cd delegate_runner
uv sync
uv run delegate-runner

Usage

Start the server:

delegate-runner [--host HOST] [--port PORT]

Options:

• --host: Bind host (default: 0.0.0.0)
• --port: Listen port (default: 3001)

MCP Tools

run_command

Execute a shell command asynchronously.

Parameters:

• command (required): Shell command to execute
• cwd (optional): Working directory
• env (optional): Extra environment variables as JSON string
• timeout (optional): Timeout in seconds

Returns: task_id

get_task_status

Get the current status of a task.

Parameters:

• task_id (required): Task identifier

Returns: Status info with running, exit_code, elapsed

get_task_output

Retrieve output lines from a task with pagination.

Parameters:

• task_id (required): Task identifier
• offset (optional): Line offset to start reading (default: 0)
• limit (optional): Max lines to return (default: 200)
• stream (optional): Filter by "stdout" or "stderr" (default: both)

cancel_task

Cancel a running task.

Parameters:

• task_id (required): Task identifier

list_tasks

List all tasks with status summaries.

Example

# Run a command
task_id = await run_command(command="ls -la", cwd="/tmp")

# Check status
status = await get_task_status(task_id)

# Get output
output = await get_task_output(task_id)

License

MIT