realdnchka/mcp-tmux-node

Tmux MCP Server

This project is a Model Context Protocol (MCP) server that acts as a bridge between an AI assistant and a tmux session. It allows the AI to inspect and interact with your terminal environment in a safe and controlled way.

The server runs inside a tmux session and exposes a set of tools that the AI can use to manage sessions, send commands, and, most importantly, understand the context of what's happening across all windows and panes.

Features

• Context-Awareness: The server's key feature is its ability to capture a complete snapshot of the current tmux session, including window/pane layouts, running commands, and recent terminal output. This allows an AI to answer questions like "What's running in the first window?" or "What was the error message from the last command?".
• Recursion Safety: The server is explicitly designed to prevent recursive loops. It will not send commands to or capture output from the specific tmux pane where it is running.
• Dynamic Interaction: Allows the AI to create and kill sessions, and to send commands to specific panes, enabling it to perform tasks on behalf of the user.

Available Tools

The server provides the following tools for the AI assistant:

• create_session: Creates a new tmux session with a given name.
• kill_session: Kills a specific tmux session by name.
• send_command: Sends a command to a pane within a specific session and returns the output. It automatically avoids sending commands to the server's own pane.
• list_sessions: Lists all currently active tmux sessions.
• get_session_context: The core tool. It returns a detailed JSON object representing the current state of the tmux session, including all windows, panes, the commands running in them, and their recent output.

Getting Started

1. Installation:

   npm install
   

2. Running the Server: The server must be run from within a tmux session.

   npm start
   

   Once started, it will listen for MCP messages on standard input.