iTerm MCP Server

Instructions

Implementation Reference

• index.js:166-190 (handler)

  The handler function retrieves the terminal by ID from the global 'terminals' map, joins its output buffer into a string, clears the buffer, and returns the output as text content or a not-found message.

  async ({ terminalId }) => {
    const terminal = terminals.get(terminalId);
    if (!terminal) {
      return {
        content: [
          {
            type: "text",
            text: `Terminal ${terminalId} not found`,
          },
        ],
      };
    }
  
    const output = terminal.output.join("");
    terminal.output.length = 0; // Clear the output buffer
  
    return {
      content: [
        {
          type: "text",
          text: output || "No output available",
        },
      ],
    };
  }

• index.js:163-165 (schema)

  Zod input schema for the tool, defining 'terminalId' as a required string parameter.

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

• index.js:160-191 (registration)

  Complete registration of the 'read-output' tool using server.tool(), including name, description, schema, and handler function.

  server.tool(
    "read-output",
    "Read the output from a specific terminal",
    {
      terminalId: z.string().describe("ID of the terminal to read output from"),
    },
    async ({ terminalId }) => {
      const terminal = terminals.get(terminalId);
      if (!terminal) {
        return {
          content: [
            {
              type: "text",
              text: `Terminal ${terminalId} not found`,
            },
          ],
        };
      }
  
      const output = terminal.output.join("");
      terminal.output.length = 0; // Clear the output buffer
  
      return {
        content: [
          {
            type: "text",
            text: output || "No output available",
          },
        ],
      };
    }
  );

• index.js:9-11 (helper)

  Global state management: Map to store active terminals (with processes and output arrays) and counter for unique IDs, essential for the read-output functionality.

  // Store active terminals
  const terminals = new Map();
  let terminalCounter = 0;