Python MCP reference

tool MCPstable

`list_windows`

List tmux windows (terminal tabs) in a session, or across the server.

Use for tmux windows — ‘current window’, ‘this tab’ (when terminal- contextual) — not browser tabs or desktop windows. Only searches window metadata (name, index, layout); to search the actual visible terminal text, use search_panes.

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

Arguments#

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

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

Session ID (e.g. ‘$1’) to look up.
session_name? = null (string | null) #

Session name to look up. If omitted along with session_id, returns windows from all sessions.
socket_name? = null (string | null) #

tmux socket name. Defaults to LIBTMUX_SOCKET env var.

No other arguments are accepted.

Result#

Returns object

result (Array<object>) #
- Items (object) #
  
  Serialized tmux window.
  - active_pane_id? = null (string | null) #
    
    Pane id (%N) of the window’s active pane.
  - pane_count (integer) #
    
    Number of panes
  - session_id? = null (string | null) #
    
    Parent session ID
  - session_name? = null (string | null) #
    
    Parent session name
  - window_active? = null (string | null) #
    
    Active flag (‘1’ or ‘0’)
  - window_height? = null (string | null) #
    
    Height in rows
  - window_id (string) #
    
    Window ID (e.g. ‘@1’)
  - window_index? = null (string | null) #
    
    Window index
  - window_layout? = null (string | null) #
    
    Layout string
  - window_name? = null (string | null) #
    
    Window name
  - window_width? = null (string | null) #
    
    Width in columns

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 (e.g. ``{\"window_name__contains\": \"dev\"}``)\nor as a JSON string. Some MCP clients require the string form."
    },
    "session_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session ID (e.g. '$1') to look up."
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session name to look up. If omitted along with session_id,\nreturns windows from all sessions."
    },
    "socket_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var."
    }
  },
  "type": "object"
}

Output schema

{
  "properties": {
    "result": {
      "items": {
        "description": "Serialized tmux window.",
        "properties": {
          "active_pane_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Pane id (``%N``) of the window's active pane."
          },
          "pane_count": {
            "description": "Number of panes",
            "type": "integer"
          },
          "session_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Parent session ID"
          },
          "session_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Parent session name"
          },
          "window_active": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Active flag ('1' or '0')"
          },
          "window_height": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Height in rows"
          },
          "window_id": {
            "description": "Window ID (e.g. '@1')",
            "type": "string"
          },
          "window_index": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Window index"
          },
          "window_layout": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Layout string"
          },
          "window_name": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Window name"
          },
          "window_width": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "default": null,
            "description": "Width in columns"
          }
        },
        "required": [
          "window_id",
          "pane_count"
        ],
        "type": "object"
      },
      "type": "array"
    }
  },
  "required": [
    "result"
  ],
  "type": "object",
  "x-fastmcp-wrap-result": true
}

Scripting & web

Compiled & native

JVM

.NET

tmux

`list_windows`

Arguments#

Result#

Annotations#

Protocol data#