Tmux MCP Server

Instructions

Implementation Reference

• src/index.ts:356-389 (handler)

  The MCP tool handler for 'execute-command'. Prepares parameters, calls tmux.executeCommand, and returns appropriate response or resource URI based on mode.

  async ({ paneId, command, rawMode, noEnter }) => {
    try {
      // If noEnter is true, automatically apply rawMode
      const effectiveRawMode = noEnter || rawMode;
      const commandId = await tmux.executeCommand(paneId, command, effectiveRawMode, noEnter);
  
      if (effectiveRawMode) {
        const modeText = noEnter ? "Keys sent without Enter" : "Interactive command started (rawMode)";
        return {
          content: [{
            type: "text",
            text: `${modeText}.\n\nStatus tracking is disabled.\nUse 'capture-pane' with paneId '${paneId}' to verify the command outcome.\n\nCommand ID: ${commandId}`
          }]
        };
      }
  
      // Create the resource URI for this command's results
      const resourceUri = `tmux://command/${commandId}/result`;
  
      return {
        content: [{
          type: "text",
          text: `Command execution started.\n\nTo get results, subscribe to and read resource: ${resourceUri}\n\nStatus will change from 'pending' to 'completed' or 'error' when finished.`
        }]
      };
    } catch (error) {
      return {
        content: [{
          type: "text",
          text: `Error executing command: ${error}`
        }],
        isError: true
      };
    }

• src/index.ts:350-355 (schema)

  Zod schema defining input parameters for the 'execute-command' tool.

  {
    paneId: z.string().describe("ID of the tmux pane"),
    command: z.string().describe("Command to execute"),
    rawMode: z.boolean().optional().describe("Execute command without wrapper markers for REPL/interactive compatibility. Disables get-command-result status tracking. Use capture-pane after execution to verify command outcome."),
    noEnter: z.boolean().optional().describe("Send keystrokes without pressing Enter. For TUI navigation in apps like btop, vim, less. Supports special keys (Up, Down, Escape, Tab, etc.) and strings (sent char-by-char for proper filtering). Automatically applies rawMode. Use capture-pane after to see results.")
  },

• src/index.ts:347-391 (registration)

  Registration of the 'execute-command' tool on the MCP server using server.tool().

  server.tool(
    "execute-command",
    "Execute a command in a tmux pane and get results. For interactive applications (REPLs, editors), use `rawMode=true`. IMPORTANT: When `rawMode=false` (default), avoid heredoc syntax (cat << EOF) and other multi-line constructs as they conflict with command wrapping. For file writing, prefer: printf 'content\\n' > file, echo statements, or write to temp files instead",
    {
      paneId: z.string().describe("ID of the tmux pane"),
      command: z.string().describe("Command to execute"),
      rawMode: z.boolean().optional().describe("Execute command without wrapper markers for REPL/interactive compatibility. Disables get-command-result status tracking. Use capture-pane after execution to verify command outcome."),
      noEnter: z.boolean().optional().describe("Send keystrokes without pressing Enter. For TUI navigation in apps like btop, vim, less. Supports special keys (Up, Down, Escape, Tab, etc.) and strings (sent char-by-char for proper filtering). Automatically applies rawMode. Use capture-pane after to see results.")
    },
    async ({ paneId, command, rawMode, noEnter }) => {
      try {
        // If noEnter is true, automatically apply rawMode
        const effectiveRawMode = noEnter || rawMode;
        const commandId = await tmux.executeCommand(paneId, command, effectiveRawMode, noEnter);
  
        if (effectiveRawMode) {
          const modeText = noEnter ? "Keys sent without Enter" : "Interactive command started (rawMode)";
          return {
            content: [{
              type: "text",
              text: `${modeText}.\n\nStatus tracking is disabled.\nUse 'capture-pane' with paneId '${paneId}' to verify the command outcome.\n\nCommand ID: ${commandId}`
            }]
          };
        }
  
        // Create the resource URI for this command's results
        const resourceUri = `tmux://command/${commandId}/result`;
  
        return {
          content: [{
            type: "text",
            text: `Command execution started.\n\nTo get results, subscribe to and read resource: ${resourceUri}\n\nStatus will change from 'pending' to 'completed' or 'error' when finished.`
          }]
        };
      } catch (error) {
        return {
          content: [{
            type: "text",
            text: `Error executing command: ${error}`
          }],
          isError: true
        };
      }
    }
  );

• src/tmux.ts:243-288 (helper)

  Helper function implementing the core logic of sending commands to a tmux pane via tmux send-keys, with support for raw mode, no-enter mode, and execution tracking.

  export async function executeCommand(paneId: string, command: string, rawMode?: boolean, noEnter?: boolean): Promise<string> {
    // Generate unique ID for this command execution
    const commandId = uuidv4();
  
    let fullCommand: string;
    if (rawMode || noEnter) {
      fullCommand = command;
    } else {
      const endMarkerText = getEndMarkerText();
      fullCommand = `echo "${startMarkerText}"; ${command}; echo "${endMarkerText}"`;
    }
  
    // Store command in tracking map
    activeCommands.set(commandId, {
      id: commandId,
      paneId,
      command,
      status: 'pending',
      startTime: new Date(),
      rawMode: rawMode || noEnter
    });
  
    // Send the command to the tmux pane
    if (noEnter) {
      // Check if this is a special key (e.g., Up, Down, Left, Right, Escape, Tab, etc.)
      // Special keys in tmux are typically capitalized or have special names
      const specialKeys = ['Up', 'Down', 'Left', 'Right', 'Escape', 'Tab', 'Enter', 'Space',
        'BSpace', 'Delete', 'Home', 'End', 'PageUp', 'PageDown',
        'F1', 'F2', 'F3', 'F4', 'F5', 'F6', 'F7', 'F8', 'F9', 'F10', 'F11', 'F12'];
  
      if (specialKeys.includes(fullCommand)) {
        // Send special key as-is
        await executeTmux(`send-keys -t '${paneId}' ${fullCommand}`);
      } else {
        // For regular text, send each character individually to ensure proper processing
        // This handles both single characters (like 'q', 'f') and strings (like 'beam')
        for (const char of fullCommand) {
          await executeTmux(`send-keys -t '${paneId}' '${char.replace(/'/g, "'\\''")}'`);
        }
      }
    } else {
      await executeTmux(`send-keys -t '${paneId}' '${fullCommand.replace(/'/g, "'\\''")}' Enter`);
    }
  
    return commandId;
  }