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