iTerm MCP Server

Instructions

Implementation Reference

• index.js:48-101 (handler)

  The inline handler function for the 'open-terminal' tool. It generates a unique terminal ID, spawns a background shell process with output collection, executes AppleScript to open a new iTerm2 tab, stores the terminal state, and returns a success message.

  server.tool("open-terminal", "Open a new terminal instance", {}, async () => {
    const terminalId = `terminal-${terminalCounter++}`;
  
    // Create both GUI terminal and background process for output collection
    const shell = process.platform === "win32" ? "cmd.exe" : "/bin/bash";
    const terminal = spawn(shell, [], {
      stdio: ["pipe", "pipe", "pipe"],
      shell: true,
    });
  
    const output = [];
  
    terminal.stdout.on("data", (data) => {
      output.push(data.toString());
    });
  
    terminal.stderr.on("data", (data) => {
      output.push(data.toString());
    });
  
    // Create iTerm window
    const script = `
      tell application "iTerm2"
        activate
        tell current window
          create tab with default profile
          tell current session
            write text "echo Terminal ${terminalId} ready"
          end tell
        end tell
      end tell
    `;
  
    try {
      await executeITermScript(script);
      terminals.set(terminalId, {
        process: terminal,
        output,
        id: terminalId,
      });
  
      return {
        content: [
          {
            type: "text",
            text: `Terminal opened with ID: ${terminalId}`,
          },
        ],
      };
    } catch (error) {
      terminal.kill(); // Clean up background process if iTerm fails
      throw error;
    }
  });

• index.js:14-39 (helper)

  Helper function used by open-terminal (and other tools) to execute AppleScript for interacting with iTerm/iTerm2 application.

  async function executeITermScript(script) {
    const execPromise = promisify(exec);
  
    // Simple launch script
    const launchScript = `
      tell application "iTerm"
        activate
      end tell
    `;
  
    try {
      // First try to launch/activate iTerm
      await execPromise(`osascript -e '${launchScript}'`);
  
      // Wait a brief moment
      await new Promise((resolve) => setTimeout(resolve, 1000));
  
      // Now execute the actual script with iTerm instead of iTerm2
      const modifiedScript = script.replace(/iTerm2/g, "iTerm");
      const { stdout } = await execPromise(`osascript -e '${modifiedScript}'`);
      return stdout.trim();
    } catch (error) {
      console.error("iTerm AppleScript error:", error);
      throw error;
    }
  }

• index.js:10-11 (helper)

  Global state management for active terminals and counter, used to track and identify terminals created by open-terminal.

  const terminals = new Map();
  let terminalCounter = 0;

• index.js:48-101 (registration)

  Registration of the 'open-terminal' tool on the MCP server, including empty schema {} and inline handler.

  server.tool("open-terminal", "Open a new terminal instance", {}, async () => {
    const terminalId = `terminal-${terminalCounter++}`;
  
    // Create both GUI terminal and background process for output collection
    const shell = process.platform === "win32" ? "cmd.exe" : "/bin/bash";
    const terminal = spawn(shell, [], {
      stdio: ["pipe", "pipe", "pipe"],
      shell: true,
    });
  
    const output = [];
  
    terminal.stdout.on("data", (data) => {
      output.push(data.toString());
    });
  
    terminal.stderr.on("data", (data) => {
      output.push(data.toString());
    });
  
    // Create iTerm window
    const script = `
      tell application "iTerm2"
        activate
        tell current window
          create tab with default profile
          tell current session
            write text "echo Terminal ${terminalId} ready"
          end tell
        end tell
      end tell
    `;
  
    try {
      await executeITermScript(script);
      terminals.set(terminalId, {
        process: terminal,
        output,
        id: terminalId,
      });
  
      return {
        content: [
          {
            type: "text",
            text: `Terminal opened with ID: ${terminalId}`,
          },
        ],
      };
    } catch (error) {
      terminal.kill(); // Clean up background process if iTerm fails
      throw error;
    }
  });