iTerm MCP Server

Instructions

Implementation Reference

• index.js:199-241 (handler)

  Handler function for the 'close-terminal' tool. Retrieves the terminal by ID from the global map, kills the background process, executes AppleScript to close the iTerm window, removes it from the map, decrements the counter, and returns a confirmation message.

    async ({ terminalId }) => {
      const terminal = terminals.get(terminalId);
      if (!terminal) {
        return {
          content: [
            {
              type: "text",
              text: `Terminal ${terminalId} not found`,
            },
          ],
        };
      }
  
      // Close both GUI and background process
      terminal.process.kill();
  
      const script = `
        tell application "iTerm2"
          close current window
        end tell
      `;
  
      try {
        await executeITermScript(script);
      } catch (error) {
        console.error("Failed to close iTerm window:", error);
      }
  
      terminals.delete(terminalId);
  
      // Safely decrement the terminal counter
      terminalCounter = Math.max(0, terminalCounter - 1);
  
      return {
        content: [
          {
            type: "text",
            text: `Terminal ${terminalId} closed`,
          },
        ],
      };
    }
  );

• index.js:196-198 (schema)

  Zod schema defining the input parameter 'terminalId' as a required string for the 'close-terminal' tool.

  {
    terminalId: z.string().describe("ID of the terminal to close"),
  },

• index.js:193-241 (registration)

  MCP server registration of the 'close-terminal' tool, including name, description, input schema, and handler function.

  server.tool(
    "close-terminal",
    "Close a specific terminal",
    {
      terminalId: z.string().describe("ID of the terminal to close"),
    },
    async ({ terminalId }) => {
      const terminal = terminals.get(terminalId);
      if (!terminal) {
        return {
          content: [
            {
              type: "text",
              text: `Terminal ${terminalId} not found`,
            },
          ],
        };
      }
  
      // Close both GUI and background process
      terminal.process.kill();
  
      const script = `
        tell application "iTerm2"
          close current window
        end tell
      `;
  
      try {
        await executeITermScript(script);
      } catch (error) {
        console.error("Failed to close iTerm window:", error);
      }
  
      terminals.delete(terminalId);
  
      // Safely decrement the terminal counter
      terminalCounter = Math.max(0, terminalCounter - 1);
  
      return {
        content: [
          {
            type: "text",
            text: `Terminal ${terminalId} closed`,
          },
        ],
      };
    }
  );

• index.js:14-39 (helper)

  Helper function used by the 'close-terminal' handler (and others) to execute AppleScript commands for iTerm2 terminal operations, including activation and script execution.

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