Tmux MCP Server

Instructions

Implementation Reference

• src/index.ts:664-691 (handler)

  The handler function that executes the tmux_capture_pane tool. It constructs the tmux capture-pane command with optional parameters for lines and escape sequences, runs it, truncates output if too long, and returns the pane content.

  },
  async ({ session, window, pane, start_line, end_line, escape_sequences }) => {
    try {
      const target = formatTarget(session, window, pane);
      let cmd = `capture-pane -t "${target}" -p`;
      if (start_line !== undefined) {
        cmd += ` -S ${start_line}`;
      }
      if (end_line !== undefined) {
        cmd += ` -E ${end_line}`;
      }
      if (escape_sequences) {
        cmd += " -e";
      }
      const output = await runTmux(cmd);
      const { text, truncated } = truncateIfNeeded(output);
  
      return {
        content: [{ type: "text", text }],
        structuredContent: { target, content: text, truncated },
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
        isError: true,
      };
    }
  }

• src/index.ts:648-657 (schema)

  Zod input schema defining parameters for the tmux_capture_pane tool: session (required), optional window, pane, start_line, end_line, escape_sequences.

  inputSchema: z
    .object({
      session: z.string().min(1).describe("Name of the session"),
      window: z.union([z.string(), z.number()]).optional().describe("Window index or name"),
      pane: z.number().int().min(0).optional().describe("Pane index"),
      start_line: z.number().int().optional().describe("Start line (negative = history)"),
      end_line: z.number().int().optional().describe("End line"),
      escape_sequences: z.boolean().default(false).describe("Include escape sequences"),
    })
    .strict(),

• src/index.ts:633-692 (registration)

  Registers the tmux_capture_pane tool using server.registerTool, including title, description, inputSchema, annotations, and the handler function.

  server.registerTool(
    "tmux_capture_pane",
    {
      title: "Capture tmux Pane Content",
      description: `Capture the visible content or history of a tmux pane.
  
  Args:
    - session (string, required): Name of the session
    - window (string or number, optional): Window index or name
    - pane (number, optional): Pane index
    - start_line (number, optional): Start line (negative = history, 0 = top of visible)
    - end_line (number, optional): End line (use - for bottom of visible pane)
    - escape_sequences (boolean, optional): Include escape sequences (default: false)
  
  This tool is useful for reading command output or checking the state of a pane.`,
      inputSchema: z
        .object({
          session: z.string().min(1).describe("Name of the session"),
          window: z.union([z.string(), z.number()]).optional().describe("Window index or name"),
          pane: z.number().int().min(0).optional().describe("Pane index"),
          start_line: z.number().int().optional().describe("Start line (negative = history)"),
          end_line: z.number().int().optional().describe("End line"),
          escape_sequences: z.boolean().default(false).describe("Include escape sequences"),
        })
        .strict(),
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ session, window, pane, start_line, end_line, escape_sequences }) => {
      try {
        const target = formatTarget(session, window, pane);
        let cmd = `capture-pane -t "${target}" -p`;
        if (start_line !== undefined) {
          cmd += ` -S ${start_line}`;
        }
        if (end_line !== undefined) {
          cmd += ` -E ${end_line}`;
        }
        if (escape_sequences) {
          cmd += " -e";
        }
        const output = await runTmux(cmd);
        const { text, truncated } = truncateIfNeeded(output);
  
        return {
          content: [{ type: "text", text }],
          structuredContent: { target, content: text, truncated },
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
          isError: true,
        };
      }
    }
  );