iTerm MCP Server

Instructions

Implementation Reference

• index.js:110-157 (handler)

  The handler function that implements the 'execute-command' tool logic: checks for terminal existence, writes the command to the background process stdin, executes an AppleScript to write the command in the iTerm2 GUI terminal, and returns appropriate success or error messages.

  async ({ terminalId, command }) => {
    const terminal = terminals.get(terminalId);
    if (!terminal) {
      return {
        content: [
          {
            type: "text",
            text: `Terminal ${terminalId} not found`,
          },
        ],
      };
    }
  
    // Execute in both GUI and background process
    terminal.process.stdin.write(command + "\n");
  
    const script = `
      tell application "iTerm2"
        tell current session of current window
          write text "${command.replace(/"/g, '\\"')}"
        end tell
      end tell
    `;
  
    try {
      await executeITermScript(script);
      // Give some time for the command to execute and output to be collected
      await new Promise((resolve) => setTimeout(resolve, 100));
  
      return {
        content: [
          {
            type: "text",
            text: `Command executed in ${terminalId}`,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: "text",
            text: `Failed to execute in GUI terminal but command ran in background: ${error.message}`,
          },
        ],
      };
    }
  }

• index.js:107-109 (schema)

  Zod schema for the 'execute-command' tool inputs: terminalId (string) and command (string).

    terminalId: z.string().describe("ID of the terminal to execute command in"),
    command: z.string().describe("Command to execute"),
  },

• index.js:103-158 (registration)

  Registration of the 'execute-command' tool using server.tool(), including name, description, schema, and handler reference.

  server.tool(
    "execute-command",
    "Execute a command in a specific terminal",
    {
      terminalId: z.string().describe("ID of the terminal to execute command in"),
      command: z.string().describe("Command to execute"),
    },
    async ({ terminalId, command }) => {
      const terminal = terminals.get(terminalId);
      if (!terminal) {
        return {
          content: [
            {
              type: "text",
              text: `Terminal ${terminalId} not found`,
            },
          ],
        };
      }
  
      // Execute in both GUI and background process
      terminal.process.stdin.write(command + "\n");
  
      const script = `
        tell application "iTerm2"
          tell current session of current window
            write text "${command.replace(/"/g, '\\"')}"
          end tell
        end tell
      `;
  
      try {
        await executeITermScript(script);
        // Give some time for the command to execute and output to be collected
        await new Promise((resolve) => setTimeout(resolve, 100));
  
        return {
          content: [
            {
              type: "text",
              text: `Command executed in ${terminalId}`,
            },
          ],
        };
      } catch (error) {
        return {
          content: [
            {
              type: "text",
              text: `Failed to execute in GUI terminal but command ran in background: ${error.message}`,
            },
          ],
        };
      }
    }
  );

• index.js:14-39 (helper)

  Helper function used by the handler to execute AppleScript commands for interacting with the iTerm terminal GUI.

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