write_to_terminal
Send text to an iTerm2 session. Optionally execute commands by appending a newline, or submit text without executing for interactive prompts.
Instructions
Send text to an iTerm2 session.
:param text: The characters to send.
:param session_id: Target session UUID. Defaults to the active session.
:param add_newline: If True (the default), appends \n so commands
execute. Set to False to type without submitting, e.g. when filling an
interactive prompt.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| text | Yes | ||
| session_id | No | ||
| add_newline | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
Implementation Reference
- src/iterm2_mcp/server.py:123-140 (handler)The write_to_terminal tool handler: sends text to an iTerm2 session. Decorated with @mcp.tool() which also serves as registration. Accepts `text`, optional `session_id`, and `add_newline` parameters.
@mcp.tool() async def write_to_terminal( text: str, session_id: str | None = None, add_newline: bool = True, ) -> str: """Send text to an iTerm2 session. :param text: The characters to send. :param session_id: Target session UUID. Defaults to the active session. :param add_newline: If True (the default), appends ``\\n`` so commands execute. Set to False to type without submitting, e.g. when filling an interactive prompt. """ sess = await _session(session_id) payload = text + "\n" if add_newline else text await sess.async_send_text(payload, suppress_broadcast=True) return f"Sent {len(payload)} characters to session {sess.session_id}" - src/iterm2_mcp/server.py:123-123 (registration)Registration via the @mcp.tool() decorator on line 123, which registers `write_to_terminal` as an MCP tool with the FastMCP instance.
@mcp.tool() - src/iterm2_mcp/server.py:124-128 (schema)The function signature serves as the schema: `text: str` (required), `session_id: str | None = None` (optional), `add_newline: bool = True` (optional, default True).
async def write_to_terminal( text: str, session_id: str | None = None, add_newline: bool = True, ) -> str: - src/iterm2_mcp/server.py:48-69 (helper)The `_session` helper function used by write_to_terminal to resolve session_id to an iTerm2 Session object, falling back to the currently active session.
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