Python MCP reference

tool MCPstable

`create_session`

Create a new tmux session.

Check list_sessions first to avoid name conflicts. A new session starts with one window and one pane. Values in environment are stored in the tmux session environment, so future panes inherit them too.

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

Arguments#

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

Environment variables to store in the session environment. Accepts either a dict of env vars or a JSON-serialized string of the same — the latter is the cursor-composer-1 workaround described in libtmux_mcp._utils._coerce_dict_arg. Each item appears in the tmux client argv as one -eKEY=VALUE element and may be visible to host process inspection during launch. tmux retains the values in tmux session state, where show-environment can reveal them. They reach the initial and future child environments unless a later spawn overrides them. MCP audit redaction does not hide these surfaces. Pass credential references, not literal credentials.
session_name? = null (string | null) #

Name for the new session.
socket_name? = null (string | null) #

tmux socket name. Defaults to LIBTMUX_SOCKET env var.
start_directory? = null (string | null) #

Existing directory to start in. ~ expands; a relative path resolves against the MCP server process’s directory.
suppress_persistent_history? = false (boolean) #

Whether to suppress persistent history for the spawned shell. Defaults to False for MCP and direct Python calls. This per-call option does not inherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these controls.
window_name? = null (string | null) #

Name for the initial window.
x? = null (integer | null) #

Width of the initial window.
y? = null (integer | null) #

Height of the initial window.

No other arguments are accepted.

Result#

Returns object

active_pane_id? = null (string | null) #

Pane id (%N) of the session’s active pane. Guaranteed non-None on create_session return (libtmux creates the session with one initial pane). May be None from list_sessions rows for sessions in transient teardown states where active_pane is unavailable.
session_attached? = null (string | null) #

Attached client count
session_created? = null (string | null) #

Creation timestamp
session_id (string) #

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

Session name
window_count (integer) #

Number of windows

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": {
    "environment": {
      "anyOf": [
        {
          "additionalProperties": {
            "type": "string"
          },
          "type": "object"
        },
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Environment variables to store in the session environment. Accepts\neither a dict of env vars or a JSON-serialized string of the same —\nthe latter is the cursor-composer-1 workaround described in\n:func:`libtmux_mcp._utils._coerce_dict_arg`. Each item appears in the\ntmux client argv as one ``-eKEY=VALUE`` element and may be visible to\nhost process inspection during launch. tmux retains the values in\ntmux session state, where ``show-environment`` can reveal them. They reach\nthe initial and future child environments unless a later spawn\noverrides them. MCP audit redaction does not hide these surfaces. Pass\ncredential references, not literal credentials."
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Name for the new session."
    },
    "socket_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "tmux socket name. Defaults to LIBTMUX_SOCKET env var."
    },
    "start_directory": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Existing directory to start in. ``~`` expands; a relative path\nresolves against the MCP server process's directory."
    },
    "suppress_persistent_history": {
      "default": false,
      "description": "Whether to suppress persistent history for the spawned shell. Defaults\nto False for MCP and direct Python calls. This per-call option does not\ninherit LIBTMUX_SUPPRESS_HISTORY. Startup files may override these\ncontrols.",
      "type": "boolean"
    },
    "window_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Name for the initial window."
    },
    "x": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Width of the initial window."
    },
    "y": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Height of the initial window."
    }
  },
  "type": "object"
}

Output schema

{
  "description": "Serialized tmux session.",
  "properties": {
    "active_pane_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Pane id (``%N``) of the session's active pane. Guaranteed non-None on ``create_session`` return (libtmux creates the session with one initial pane). May be None from ``list_sessions`` rows for sessions in transient teardown states where ``active_pane`` is unavailable."
    },
    "session_attached": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Attached client count"
    },
    "session_created": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Creation timestamp"
    },
    "session_id": {
      "description": "Session ID (e.g. '$1')",
      "type": "string"
    },
    "session_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "description": "Session name"
    },
    "window_count": {
      "description": "Number of windows",
      "type": "integer"
    }
  },
  "required": [
    "session_id",
    "window_count"
  ],
  "type": "object"
}

Scripting & web

Compiled & native

JVM

.NET

tmux

`create_session`

Arguments#

Result#

Annotations#

Protocol data#