tmux

This MCP server exposes a set of tools that let AI agents interact with terminal tmux sessions. The available tools include: start_session, which creates a new tmux session; send_commands, which types commands or keystrokes into a session (with support for special keys like <ENTER> and <ESC>); view_session, which captures and returns the current screen contents of a session; list_sessions, which enumerates all active tmux sessions; join_session, which attaches to or attaches an agent to an existing session; and close_session, which terminates a session. You operate by sending structured tool calls (as shown in examples) to perform common terminal automation tasks such as editing files with vim, running commands, or streaming session output for review. The server communicates via stdio, so you send JSON-encoded tool calls and receive JSON responses describing the result or next actions.

Prerequisites:

• Go 1.24.2 or newer
• tmux installed on the host

1. Install Go if you haven't already. Visit https://golang.org/dl/ and follow installation instructions for your OS.

2. Ensure tmux is installed and accessible from your PATH (tmux --version).

3. Clone the MCP server repository or download the source code.

4. Build and run the server:

   go run ./cmd/tmux-mcp-server

5. Verify the server starts and is ready to accept stdio-based MCP tool calls. You should see startup logs indicating the server is listening on stdout/stdin.

Optional: If you prefer building a binary first, you can also run:

go build ./cmd/tmux-mcp-server ./tmux-mcp-server

Note: This server uses Hermit for development environment management, but running it via the standard Go toolchain is sufficient for local usage.

Tips and considerations:

• The server communicates through stdio; ensure your client correctly formats and parses JSON tool calls and responses.
• Tools support plain strings (typed text) and special keys via the <KEY> format (e.g., <ENTER>, <ESC>, <TAB>).
• tmux sessions persist in the background; use list_sessions to monitor active ones and close_session when done to free resources.
• When automating vim or other full-screen applications, ensure the commands sequence includes proper navigation and exits to avoid leaving the terminal in an inconsistent state.
• If you encounter permission or path issues with tmux, confirm that the user running the server has access to run tmux and the necessary shell environment.
• This server relies on Go 1.24.2+; using an older Go version may cause compilation errors.