Tmux MCP Server

Instructions

Implementation Reference

• src/index.ts:609-630 (handler)

  The handler function that sends the specified keys to the target tmux pane using the tmux 'send-keys' command. It handles targeting, key escaping, optional Enter press, execution via runTmux utility, and formats success/error responses.

  async ({ session, window, pane, keys, enter }) => {
    try {
      const target = formatTarget(session, window, pane);
      // Escape double quotes in keys
      const escapedKeys = keys.replace(/"/g, '\\"');
      let cmd = `send-keys -t "${target}" "${escapedKeys}"`;
      if (enter) {
        cmd += " Enter";
      }
      await runTmux(cmd);
  
      return {
        content: [{ type: "text", text: `Keys sent to ${target || "current pane"}: "${keys}"${enter ? " [Enter]" : ""}` }],
        structuredContent: { success: true, target, keys, enter },
      };
    } catch (error) {
      return {
        content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
        isError: true,
      };
    }
  }

• src/index.ts:593-601 (schema)

  Zod input schema defining the parameters for the tmux_send_keys tool: session (required string), window (optional string/number), pane (optional number), keys (required string), enter (optional boolean, default true).

  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"),
      keys: z.string().min(1).describe("Keys or command to send"),
      enter: z.boolean().default(true).describe("Press Enter after sending keys"),
    })
    .strict(),

• src/index.ts:576-631 (registration)

  The server.registerTool call that registers the tmux_send_keys tool with the MCP server, providing title, description, input schema, annotations, and the handler function.

  server.registerTool(
    "tmux_send_keys",
    {
      title: "Send Keys to tmux Pane",
      description: `Send keys or commands to 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
    - keys (string, required): Keys or command to send
    - enter (boolean, optional): Press Enter after sending keys (default: true)
  
  Examples:
    - Send a command: keys="ls -la", enter=true
    - Send text without executing: keys="echo hello", enter=false
    - Send special keys: keys="C-c" (Ctrl+C), keys="C-d" (Ctrl+D)`,
      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"),
          keys: z.string().min(1).describe("Keys or command to send"),
          enter: z.boolean().default(true).describe("Press Enter after sending keys"),
        })
        .strict(),
      annotations: {
        readOnlyHint: false,
        destructiveHint: false,
        idempotentHint: false,
        openWorldHint: false,
      },
    },
    async ({ session, window, pane, keys, enter }) => {
      try {
        const target = formatTarget(session, window, pane);
        // Escape double quotes in keys
        const escapedKeys = keys.replace(/"/g, '\\"');
        let cmd = `send-keys -t "${target}" "${escapedKeys}"`;
        if (enter) {
          cmd += " Enter";
        }
        await runTmux(cmd);
  
        return {
          content: [{ type: "text", text: `Keys sent to ${target || "current pane"}: "${keys}"${enter ? " [Enter]" : ""}` }],
          structuredContent: { success: true, target, keys, enter },
        };
      } catch (error) {
        return {
          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
          isError: true,
        };
      }
    }
  );

• src/index.ts:70-82 (helper)

  Utility function formatTarget used by the handler to construct the tmux target string (session:window.pane).

  function formatTarget(session?: string, window?: number | string, pane?: number): string {
    let target = "";
    if (session) {
      target = session;
      if (window !== undefined) {
        target += `:${window}`;
        if (pane !== undefined) {
          target += `.${pane}`;
        }
      }
    }
    return target;
  }

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

  Utility function runTmux that executes tmux commands via child_process.exec, handles common errors with user-friendly messages, and returns trimmed stdout.

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