iTerm MCP

Instructions

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}`);
    }
  }