Python MCP reference

tool MCPstable

`list_panes`

List tmux panes (terminal multiplexer splits) in a window, session, or server.

Use for terminal panes — including ‘this pane’, ‘current pane’, ‘split pane’, ‘the bottom shell’ — not editor splits or browser panes. Only searches pane metadata (current command, title, working directory); to search the actual visible terminal text, use search_panes.

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

Arguments#

filters? = null (Record<string, string> | string | null) #

Django-style filters as a dict (e.g. {"pane_current_command__contains": "vim"}) or as a JSON string. Some MCP clients require the string form.
session_id? = null (string | null) #

Session ID. If given without window params, lists all panes in the session.
session_name? = null (string | null) #

Session name. If given without window params, lists all panes in the session.
socket_name? = null (string | null) #

tmux socket name.
window_id? = null (string | null) #

Window ID (e.g. ‘@1’). Scopes to a single window.
window_index? = null (string | null) #

Window index within the session. Scopes to a single window.

No other arguments are accepted.

Result#

Returns object

result (Array<object>) #
- Items (object) #
  
  Serialized tmux pane.
  - is_caller? = null (boolean | null) #
    
    MCP caller identity for this pane. True when the pane matches the caller’s TMUX_PANE and lives on the same tmux socket as the caller’s TMUX (verified via socket realpath); False otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; None when the MCP process is not running inside tmux at all.
  - pane_active? = null (string | null) #
    
    Active flag (‘1’ or ‘0’)
  - pane_at_bottom? = null (boolean | null) #
    
    True when the pane touches the window’s bottom edge.
  - pane_at_left? = null (boolean | null) #
    
    True when the pane touches the window’s left edge.
  - pane_at_right? = null (boolean | null) #
    
    True when the pane touches the window’s right edge.
  - pane_at_top? = null (boolean | null) #
    
    True when the pane touches the window’s top edge. tmux accounts for pane-border-status here, so the top row may be 1 instead of 0 when the status bar is at the top.
  - pane_bottom? = null (integer | null) #
    
    Bottom edge row (inclusive), window-relative.
  - pane_current_command? = null (string | null) #
    
    Running command
  - pane_current_path? = null (string | null) #
    
    Current working directory
  - pane_height? = null (string | null) #
    
    Height in rows
  - pane_id (string) #
    
    Pane ID (e.g. ‘%1’)
  - pane_index? = null (string | null) #
    
    Pane index
  - pane_left? = null (integer | null) #
    
    Left edge column, 0-based and window-relative.
  - pane_pid? = null (string | null) #
    
    Process ID
  - pane_right? = null (integer | null) #
    
    Right edge column (inclusive), window-relative.
  - pane_title? = null (string | null) #
    
    Pane title
  - pane_top? = null (integer | null) #
    
    Top edge row, 0-based and window-relative.
  - pane_tty? = null (string | null) #
    
    TTY device path of the pane (e.g. ‘/dev/pts/5’).
  - pane_width? = null (string | null) #
    
    Width in columns
  - session_id? = null (string | null) #
    
    Parent session ID
  - window_id? = null (string | null) #
    
    Parent window ID

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": {
    "filters": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Django-style filters as a dict\n(e.g. ``{\"pane_current_command__contains\": \"vim\"}``)\nor as a JSON string. Some MCP clients require the string form."
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session ID. If given without window params, lists all panes\nin the session."
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session name. If given without window params, lists all panes\nin the session."
    },
    "socket_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "tmux socket name."
    },
    "window_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window ID (e.g. '@1'). Scopes to a single window."
    },
    "window_index": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Window index within the session. Scopes to a single window."
    }
  },
  "type": "object"
}

Output schema

{
  "properties": {
    "result": {
      "items": {
        "description": "Serialized tmux pane.",
        "properties": {
          "is_caller": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "MCP caller identity for this pane. ``True`` when the pane matches the caller's ``TMUX_PANE`` *and* lives on the same tmux socket as the caller's ``TMUX`` (verified via socket realpath); ``False`` otherwise, including the case where the pane id matches but the socket does not or cannot be proven to; ``None`` when the MCP process is not running inside tmux at all."
          },
          "pane_active": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Active flag ('1' or '0')"
          },
          "pane_at_bottom": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "True when the pane touches the window's bottom edge."
          },
          "pane_at_left": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "True when the pane touches the window's left edge."
          },
          "pane_at_right": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "True when the pane touches the window's right edge."
          },
          "pane_at_top": {
            "anyOf": [
              {
                "type": "boolean"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "True when the pane touches the window's top edge. tmux accounts for ``pane-border-status`` here, so the top row may be 1 instead of 0 when the status bar is at the top."
          },
          "pane_bottom": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Bottom edge row (inclusive), window-relative."
          },
          "pane_current_command": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Running command"
          },
          "pane_current_path": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Current working directory"
          },
          "pane_height": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Height in rows"
          },
          "pane_id": {
            "description": "Pane ID (e.g. '%1')",
            "type": "string"
          },
          "pane_index": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Pane index"
          },
          "pane_left": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Left edge column, 0-based and window-relative."
          },
          "pane_pid": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Process ID"
          },
          "pane_right": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Right edge column (inclusive), window-relative."
          },
          "pane_title": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Pane title"
          },
          "pane_top": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Top edge row, 0-based and window-relative."
          },
          "pane_tty": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "TTY device path of the pane (e.g. '/dev/pts/5')."
          },
          "pane_width": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Width in columns"
          },
          "session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Parent session ID"
          },
          "window_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Parent window ID"
          }
        },
        "required": [
          "pane_id"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

Scripting & web

Compiled & native

JVM

.NET

tmux

`list_panes`

Arguments#

Result#

Annotations#

Protocol data#