Tmux MCP Server

Instructions

Implementation Reference

• src/index.ts:277-311 (handler)

  Main handler function that lists windows in the specified tmux session by executing 'tmux list-windows' with a custom format, parsing the output into TmuxWindow objects (index, name, active status, pane count), handling empty results and errors, and returning both text and structured JSON content.

  async ({ session }) => {
    try {
      const output = await runTmux(
        `list-windows -t "${session}" -F "#{window_index}|#{window_name}|#{window_active}|#{window_panes}"`
      );
  
      if (!output) {
        return {
          content: [{ type: "text", text: `No windows found in session '${session}'.` }],
        };
      }
  
      const windows: TmuxWindow[] = output.split("\n").map((line) => {
        const [index, name, active, panes] = line.split("|");
        return {
          index: parseInt(index, 10),
          name,
          active: active === "1",
          panes: parseInt(panes, 10),
        };
      });
  
      const result = { session, count: windows.length, windows };
  
      return {
        content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
        structuredContent: result,
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
        isError: true,
      };
    }
  }

• src/index.ts:265-269 (schema)

  Zod input schema defining the required 'session' parameter as a non-empty string.

  inputSchema: z
    .object({
      session: z.string().min(1).describe("Name of the session"),
    })
    .strict(),

• src/index.ts:29-33 (schema)

  TypeScript interface defining the structure of a tmux window object used in the tool's output.

    index: number;
    name: string;
    active: boolean;
    panes: number;
  }

• src/index.ts:255-312 (registration)

  Full registration of the tmux_list_windows tool with McpServer, including name, tool specification (title, description, input schema, annotations), and inline handler function.

  server.registerTool(
    "tmux_list_windows",
    {
      title: "List tmux Windows",
      description: `List all windows in a tmux session.
  
  Args:
    - session (string, required): Name of the session
  
  Returns information about each window including index, name, active status, and pane count.`,
      inputSchema: z
        .object({
          session: z.string().min(1).describe("Name of the session"),
        })
        .strict(),
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ session }) => {
      try {
        const output = await runTmux(
          `list-windows -t "${session}" -F "#{window_index}|#{window_name}|#{window_active}|#{window_panes}"`
        );
  
        if (!output) {
          return {
            content: [{ type: "text", text: `No windows found in session '${session}'.` }],
          };
        }
  
        const windows: TmuxWindow[] = output.split("\n").map((line) => {
          const [index, name, active, panes] = line.split("|");
          return {
            index: parseInt(index, 10),
            name,
            active: active === "1",
            panes: parseInt(panes, 10),
          };
        });
  
        const result = { session, count: windows.length, windows };
  
        return {
          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
          structuredContent: result,
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
          isError: true,
        };
      }
    }
  );

• src/index.ts:45-68 (helper)

  Utility function to execute tmux commands asynchronously, handling common errors like no server, session/window/pane not found with helpful messages referencing this tool.

  async function runTmux(args: string): Promise<string> {
    try {
      const { stdout } = await execAsync(`tmux ${args}`);
      return stdout.trim();
    } catch (error: unknown) {
      if (error instanceof Error && "stderr" in error) {
        const stderr = (error as { stderr: string }).stderr;
        if (stderr.includes("no server running")) {
          throw new Error("tmux server is not running. Start a session first with tmux_create_session.");
        }
        if (stderr.includes("session not found")) {
          throw new Error("Session not found. Use tmux_list_sessions to see available sessions.");
        }
        if (stderr.includes("window not found")) {
          throw new Error("Window not found. Use tmux_list_windows to see available windows.");
        }
        if (stderr.includes("can't find pane")) {
          throw new Error("Pane not found. Use tmux_list_panes to see available panes.");
        }
        throw new Error(`tmux error: ${stderr}`);
      }
      throw error;
    }
  }