Tmux MCP Server

Instructions

Implementation Reference

• src/index.ts:81-106 (registration)

  MCP server.tool registration for the 'list-windows' tool, including description, input schema (sessionId), and inline async handler that calls tmux.listWindows and returns formatted JSON response or error.

  server.tool(
    "list-windows",
    "List windows in a tmux session",
    {
      sessionId: z.string().describe("ID of the tmux session")
    },
    async ({ sessionId }) => {
      try {
        const windows = await tmux.listWindows(sessionId);
        return {
          content: [{
            type: "text",
            text: JSON.stringify(windows, null, 2)
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error listing windows: ${error}`
          }],
          isError: true
        };
      }
    }
  );

• src/index.ts:84-86 (schema)

  Zod input schema for the list-windows tool requiring a sessionId string parameter.

  {
    sessionId: z.string().describe("ID of the tmux session")
  },

• src/index.ts:87-105 (handler)

  Inline handler function for list-windows tool execution logic.

  async ({ sessionId }) => {
    try {
      const windows = await tmux.listWindows(sessionId);
      return {
        content: [{
          type: "text",
          text: JSON.stringify(windows, null, 2)
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error listing windows: ${error}`
        }],
        isError: true
      };
    }
  }

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

  Core helper function listWindows that executes the tmux 'list-windows' command, parses the output using custom format, and returns array of TmuxWindow objects.

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

• src/tmux.ts:15-20 (schema)

  TypeScript interface defining the structure of TmuxWindow objects returned by the listWindows helper.

  export interface TmuxWindow {
    id: string;
    name: string;
    active: boolean;
    sessionId: string;
  }