write_to_terminal
Execute commands or write text directly to your active iTerm terminal session through the iTerm MCP server.
Instructions
Writes text to the active iTerm terminal - often used to run a command in the terminal
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | The command to run or text to write to the terminal |
Implementation Reference
- src/index.ts:76-94 (handler)Handler for the 'write_to_terminal' tool: executes the command via CommandExecutor, measures output lines using TtyOutputReader, and returns a descriptive message.case "write_to_terminal": { let executor = new CommandExecutor(); const command = String(request.params.arguments?.command); const beforeCommandBuffer = await TtyOutputReader.retrieveBuffer(); const beforeCommandBufferLines = beforeCommandBuffer.split("\n").length; await executor.executeCommand(command); const afterCommandBuffer = await TtyOutputReader.retrieveBuffer(); const afterCommandBufferLines = afterCommandBuffer.split("\n").length; const outputLines = afterCommandBufferLines - beforeCommandBufferLines return { content: [{ type: "text", text: `${outputLines} lines were output after sending the command to the terminal. Read the last ${outputLines} lines of terminal contents to orient yourself. Never assume that the command was executed or that it was successful.` }] }; }
- src/index.ts:28-41 (schema)Tool specification including name, description, and input schema for 'write_to_terminal'.{ name: "write_to_terminal", description: "Writes text to the active iTerm terminal - often used to run a command in the terminal", inputSchema: { type: "object", properties: { command: { type: "string", description: "The command to run or text to write to the terminal" }, }, required: ["command"] } },
- src/index.ts:25-72 (registration)Registration of all tools including 'write_to_terminal' via the ListToolsRequestHandler.server.setRequestHandler(ListToolsRequestSchema, async () => { return { tools: [ { name: "write_to_terminal", description: "Writes text to the active iTerm terminal - often used to run a command in the terminal", inputSchema: { type: "object", properties: { command: { type: "string", description: "The command to run or text to write to the terminal" }, }, required: ["command"] } }, { name: "read_terminal_output", description: "Reads the output from the active iTerm terminal", inputSchema: { type: "object", properties: { linesOfOutput: { type: "number", description: "The number of lines of output to read." }, }, required: ["linesOfOutput"] } }, { name: "send_control_character", description: "Sends a control character to the active iTerm terminal (e.g., Control-C)", inputSchema: { type: "object", properties: { letter: { type: "string", description: "The letter corresponding to the control character (e.g., 'C' for Control-C)" }, }, required: ["letter"] } } ] }; });
- src/CommandExecutor.ts:13-37 (helper)Core implementation in CommandExecutor.executeCommand: escapes command and uses osascript to write to iTerm2 current session, waits for completion.async executeCommand(command: string): Promise<string> { const escapedCommand = this.escapeForAppleScript(command); try { await execPromise(`/usr/bin/osascript -e 'tell application "iTerm2" to tell current session of current window to write text "${escapedCommand}"'`); // Wait until iterm reports that processing is done while (await this.isProcessing()) { await sleep(100); } const ttyPath = await this.retrieveTtyPath(); while (await this.isWaitingForUserInput(ttyPath) === false) { await sleep(100); } // Give a small delay for output to settle await sleep(200); const afterCommandBuffer = await TtyOutputReader.retrieveBuffer() return afterCommandBuffer } catch (error: unknown) { throw new Error(`Failed to execute command: ${(error as Error).message}`); } }