iTerm MCP Server

Instructions

Implementation Reference

• src/index.ts:28-41 (registration)

  Registration of the write_to_terminal tool, defining its name, description, and input schema.
  { 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:76-94 (handler)

  MCP tool handler for write_to_terminal: executes the command using CommandExecutor, measures output lines before/after using TtyOutputReader.
  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/CommandExecutor.ts:38-72 (handler)

  Core implementation of writing the command to iTerm2 terminal via AppleScript (handles single/multiline, waits for completion).
  async executeCommand(command: string): Promise<string> { const escapedCommand = this.escapeForAppleScript(command); try { // Check if this is a multiline command (which would have been processed differently) if (command.includes('\n')) { // For multiline text, we use parentheses around our prepared string expression // This allows AppleScript to evaluate the string concatenation expression await this._execPromise(`/usr/bin/osascript -e 'tell application "iTerm2" to tell current session of current window to write text (${escapedCommand})'`); } else { // For single line commands, we can use the standard approach with quoted strings await this._execPromise(`/usr/bin/osascript -e 'tell application "iTerm2" to tell current session of current window to write text "${escapedCommand}"'`); } // Wait until iTerm2 reports that command processing is complete while (await this.isProcessing()) { await sleep(100); } // Get the TTY path and check if it's waiting for user input 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); // Retrieve the terminal output after command execution const afterCommandBuffer = await TtyOutputReader.retrieveBuffer() return afterCommandBuffer } catch (error: unknown) { throw new Error(`Failed to execute command: ${(error as Error).message}`); } }
• src/TtyOutputReader.ts:16-31 (helper)

  Helper method to retrieve the current terminal buffer contents via AppleScript, used before/after command execution.
  static async retrieveBuffer(): Promise<string> { const ascript = ` tell application "iTerm2" tell front window tell current session of current tab set numRows to number of rows set allContent to contents return allContent end tell end tell end tell `; const { stdout: finalContent } = await execPromise(`osascript -e '${ascript}'`); return finalContent.trim(); }
• src/index.ts:31-40 (schema)

  Input schema definition for the write_to_terminal tool.
  inputSchema: { type: "object", properties: { command: { type: "string", description: "The command to run or text to write to the terminal" }, }, required: ["command"] }