Tmux MCP Server

Instructions

Implementation Reference

• src/index.ts:189-210 (handler)

  Handler function that executes tmux new-session command with optional window name and start directory.

  async ({ name, window_name, start_directory }) => {
    try {
      let cmd = `new-session -d -s "${name}"`;
      if (window_name) {
        cmd += ` -n "${window_name}"`;
      }
      if (start_directory) {
        cmd += ` -c "${start_directory}"`;
      }
      await runTmux(cmd);
  
      return {
        content: [{ type: "text", text: `Session '${name}' created successfully.` }],
        structuredContent: { success: true, session: name },
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
        isError: true,
      };
    }
  }

• src/index.ts:175-181 (schema)

  Zod schema for input validation: name (required string), window_name and start_directory (optional strings).

  inputSchema: z
    .object({
      name: z.string().min(1).describe("Name for the new session"),
      window_name: z.string().optional().describe("Name for the initial window"),
      start_directory: z.string().optional().describe("Starting directory for the session"),
    })
    .strict(),

• src/index.ts:163-211 (registration)

  Registration of the tmux_create_session tool using server.registerTool, including title, description, schema, annotations, and handler.

  server.registerTool(
    "tmux_create_session",
    {
      title: "Create tmux Session",
      description: `Create a new tmux session.
  
  Args:
    - name (string, required): Name for the new session
    - window_name (string, optional): Name for the initial window
    - start_directory (string, optional): Starting directory for the session
  
  The session is created in detached mode. Use this to start new working environments.`,
      inputSchema: z
        .object({
          name: z.string().min(1).describe("Name for the new session"),
          window_name: z.string().optional().describe("Name for the initial window"),
          start_directory: z.string().optional().describe("Starting directory for the session"),
        })
        .strict(),
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: false,
      },
    },
    async ({ name, window_name, start_directory }) => {
      try {
        let cmd = `new-session -d -s "${name}"`;
        if (window_name) {
          cmd += ` -n "${window_name}"`;
        }
        if (start_directory) {
          cmd += ` -c "${start_directory}"`;
        }
        await runTmux(cmd);
  
        return {
          content: [{ type: "text", text: `Session '${name}' created successfully.` }],
          structuredContent: { success: true, session: name },
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
          isError: true,
        };
      }
    }
  );

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

  Utility function runTmux that executes tmux commands and handles common errors, used by the handler.

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