send_escape_sequence
Send raw escape sequences to iTerm2 sessions. Supports Python string escapes for control codes like clear screen or cursor home.
Instructions
Send a raw escape sequence to an iTerm2 session.
Python string escapes in sequence are interpreted before sending, so
values like \x1b[2J (clear screen) or \x1b[H (cursor home) work
as expected.
:param sequence: The escape sequence string. :param session_id: Target session UUID. Defaults to the active session.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| sequence | Yes | ||
| session_id | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/iterm2_mcp/server.py:170-189 (handler)The async function `send_escape_sequence` implementing the tool logic. It takes a `sequence` string and optional `session_id`, interprets Python escape sequences via latin-1 round-trip, and sends the result via iTerm2's async_send_text.
@mcp.tool() async def send_escape_sequence( sequence: str, session_id: str | None = None, ) -> str: """Send a raw escape sequence to an iTerm2 session. Python string escapes in ``sequence`` are interpreted before sending, so values like ``\\x1b[2J`` (clear screen) or ``\\x1b[H`` (cursor home) work as expected. :param sequence: The escape sequence string. :param session_id: Target session UUID. Defaults to the active session. """ # Round-trip through latin-1 so Python interprets escape sequences like \x1b. # This only works for characters in the latin-1 range (0x00-0xFF). cooked = sequence.encode("latin-1").decode("unicode_escape") sess = await _session(session_id) await sess.async_send_text(cooked, suppress_broadcast=True) return f"Sent {len(cooked)} bytes to session {sess.session_id}" - src/iterm2_mcp/server.py:170-170 (registration)The `@mcp.tool()` decorator registers `send_escape_sequence` as an MCP tool on the FastMCP instance named 'iterm2-mcp'.
@mcp.tool() - src/iterm2_mcp/server.py:171-174 (schema)The function signature defines the schema: `sequence: str` (required) and `session_id: str | None` (optional, defaults to active session).
async def send_escape_sequence( sequence: str, session_id: str | None = None, ) -> str: - src/iterm2_mcp/server.py:48-69 (helper)The `_session()` helper resolves the session_id or falls back to the currently active session, used by send_escape_sequence and other tools.
async def _session(session_id: str | None) -> iterm2.Session: """Resolve a session by ID, falling back to the currently active session. :param session_id: A specific session UUID to target, or ``None`` to use the currently focused window/tab/pane. """ app = await _app() if session_id: sess = app.get_session_by_id(session_id) if sess is None: raise ValueError(f"No session found with ID {session_id!r}") return sess win = app.current_terminal_window if win is None: raise RuntimeError("No active iTerm2 window.") tab = win.current_tab if tab is None: raise RuntimeError("No active tab in the current window.") sess = tab.current_session if sess is None: raise RuntimeError("No active session in the current tab.") return sess