Python MCP reference

tool MCPstable

`run_command`

Run a shell command in a pane, wait for completion, and capture output.

Use for the common terminal workflow: run this command, wait until it completes, then report whether it succeeded. The command is sent to the pane’s interactive shell, followed by a private tmux wait-for signal and a private pane option carrying the shell exit status. This is the AUTHORED-output path — the command you pass is what the wait synchronizes on. Reserve wait_for_text for output you did not author: another process, a human, or a background job.

The command runs in a subshell, so cd, export and other shell state changes do not persist to later calls.

MCP request method: tools/call Send run_command as the tool name, with the arguments below.

Arguments#

command (string) #

Shell command to run in the target pane.
max_lines? = null (integer | null) #

Maximum pane output lines to return. Defaults to all captured visible output; pass a small value for a tail-only summary.
pane_id? = null (string | null) #

Pane ID (e.g. ‘%1’).
session_id? = null (string | null) #

Session ID (e.g. ‘$1’) for pane resolution.
session_name? = null (string | null) #

Session name for pane resolution.
socket_name? = null (string | null) #

tmux socket name.
suppress_history? = true (boolean) #

For MCP calls, omission uses the server’s LIBTMUX_SUPPRESS_HISTORY default; an explicit value overrides it. Direct Python calls default to False. Best effort: the shell must honor space-prefixed history suppression. Suppression requires a single-line command; multiline commands remain available when suppression is false.
timeout? = 30 (number) #

Maximum seconds to wait for command completion. Capped by the same server wait ceiling as wait_for_text; an over-large value is not an error — the wait returns at the ceiling and the timeout actually enforced is reported on RunCommandResult.effective_timeout.
window_id? = null (string | null) #

Window ID for pane resolution.

No other arguments are accepted.

Result#

Returns object

effective_timeout (number) #

Seconds actually enforced for command completion. Server policy caps the requested timeout; compare against what you passed to see a clamp.
elapsed_seconds (number) #

Time spent waiting in seconds
exit_status? = null (integer | null) #

Shell exit status, or None when the command timed out
output? (Array<string>) #

Tail-preserved pane output after the wait completes
output_truncated? = false (boolean) #

True when output was tail-preserved to stay within max_lines
output_truncated_lines? = 0 (integer) #

Number of pane lines dropped from the head when truncating
pane_id (string) #

Pane ID that received the command
timed_out (boolean) #

True when the wait timed out

Annotations#

destructiveHint: true
idempotentHint: false
openWorldHint: true
readOnlyHint: false

Protocol data#

Use the complete advertised contract for validation and client integration.

Input schema

{
  "additionalProperties": false,
  "properties": {
    "command": {
      "description": "Shell command to run in the target pane.",
      "type": "string"
    },
    "max_lines": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Maximum pane output lines to return. Defaults to all captured\nvisible output; pass a small value for a tail-only summary."
    },
    "pane_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pane ID (e.g. '%1')."
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session ID (e.g. '$1') for pane resolution."
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session name for pane resolution."
    },
    "socket_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "tmux socket name."
    },
    "suppress_history": {
      "default": true,
      "description": "For MCP calls, omission uses the server's LIBTMUX_SUPPRESS_HISTORY\ndefault; an explicit value overrides it. Direct Python calls default\nto False. Best effort: the shell must honor space-prefixed history\nsuppression. Suppression requires a single-line command; multiline\ncommands remain available when suppression is false.",
      "type": "boolean"
    },
    "timeout": {
      "default": 30,
      "description": "Maximum seconds to wait for command completion. Capped by the\nsame server wait ceiling as ``wait_for_text``; an over-large\nvalue is not an error — the wait returns at the ceiling and\nthe timeout actually enforced is reported on\n``RunCommandResult.effective_timeout``.",
      "type": "number"
    },
    "window_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window ID for pane resolution."
    }
  },
  "required": [
    "command"
  ],
  "type": "object"
}

Output schema

{
  "description": "Result of running a shell command in a pane.",
  "properties": {
    "effective_timeout": {
      "description": "Seconds actually enforced for command completion. Server policy caps the requested ``timeout``; compare against what you passed to see a clamp.",
      "type": "number"
    },
    "elapsed_seconds": {
      "description": "Time spent waiting in seconds",
      "type": "number"
    },
    "exit_status": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Shell exit status, or None when the command timed out"
    },
    "output": {
      "description": "Tail-preserved pane output after the wait completes",
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "output_truncated": {
      "default": false,
      "description": "True when output was tail-preserved to stay within max_lines",
      "type": "boolean"
    },
    "output_truncated_lines": {
      "default": 0,
      "description": "Number of pane lines dropped from the head when truncating",
      "type": "integer"
    },
    "pane_id": {
      "description": "Pane ID that received the command",
      "type": "string"
    },
    "timed_out": {
      "description": "True when the wait timed out",
      "type": "boolean"
    }
  },
  "required": [
    "pane_id",
    "timed_out",
    "elapsed_seconds",
    "effective_timeout"
  ],
  "type": "object"
}

Scripting & web

Compiled & native

JVM

.NET

tmux

`run_command`

Arguments#

Result#

Annotations#

Protocol data#