Tmux MCP Server

Instructions

Implementation Reference

• src/index.ts:200-228 (registration)

  Registration of the MCP 'create-window' tool, including input schema and inline handler function that calls tmux.createWindow

  server.tool(
    "create-window",
    "Create a new window in a tmux session",
    {
      sessionId: z.string().describe("ID of the tmux session"),
      name: z.string().describe("Name for the new window")
    },
    async ({ sessionId, name }) => {
      try {
        const window = await tmux.createWindow(sessionId, name);
        return {
          content: [{
            type: "text",
            text: window
              ? `Window created: ${JSON.stringify(window, null, 2)}`
              : `Failed to create window: ${name}`
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error creating window: ${error}`
          }],
          isError: true
        };
      }
    }
  );

• src/index.ts:203-206 (schema)

  Input schema for create-window tool using Zod validation

  {
    sessionId: z.string().describe("ID of the tmux session"),
    name: z.string().describe("Name for the new window")
  },

• src/index.ts:207-226 (handler)

  MCP tool handler for create-window, which delegates to tmux.createWindow and formats response

  async ({ sessionId, name }) => {
    try {
      const window = await tmux.createWindow(sessionId, name);
      return {
        content: [{
          type: "text",
          text: window
            ? `Window created: ${JSON.stringify(window, null, 2)}`
            : `Failed to create window: ${name}`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error creating window: ${error}`
        }],
        isError: true
      };
    }

• src/tmux.ts:170-174 (handler)

  Core implementation of createWindow: executes tmux new-window command and retrieves the new window info

  export async function createWindow(sessionId: string, name: string): Promise<TmuxWindow | null> {
    const output = await executeTmux(`new-window -t '${sessionId}' -n '${name}'`);
    const windows = await listWindows(sessionId);
    return windows.find(window => window.name === name) || null;
  }

• src/tmux.ts:114-129 (helper)

  Helper function listWindows used by createWindow to find the newly created window

  export async function listWindows(sessionId: string): Promise<TmuxWindow[]> {
    const format = "#{window_id}:#{window_name}:#{?window_active,1,0}";
    const output = await executeTmux(`list-windows -t '${sessionId}' -F '${format}'`);
  
    if (!output) return [];
  
    return output.split('\n').map(line => {
      const [id, name, active] = line.split(':');
      return {
        id,
        name,
        active: active === '1',
        sessionId
      };
    });
  }