Tmux MCP Server

Instructions

Implementation Reference

• src/tmux.ts:134-149 (handler)

  Core handler function that executes the tmux 'list-panes' command, parses the formatted output into TmuxPane objects, and returns the list of panes.

  export async function listPanes(windowId: string): Promise<TmuxPane[]> {
    const format = "#{pane_id}:#{pane_title}:#{?pane_active,1,0}";
    const output = await executeTmux(`list-panes -t '${windowId}' -F '${format}'`);
  
    if (!output) return [];
  
    return output.split('\n').map(line => {
      const [id, title, active] = line.split(':');
      return {
        id,
        windowId,
        title: title,
        active: active === '1'
      };
    });
  }

• src/index.ts:109-134 (registration)

  MCP tool registration for 'list-panes', including input schema (windowId: string) and thin wrapper handler that calls tmux.listPanes and returns JSON response.

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

• src/tmux.ts:22-27 (schema)

  TypeScript interface defining the structure of a TmuxPane object, used as output type for listPanes.

  export interface TmuxPane {
    id: string;
    windowId: string;
    active: boolean;
    title: string;
  }