tmux-mcp

@fr1sk

About tmux-mcp

No overview available yet

#tmux #terminal #mcp #developer-tools #shell #bash #logs #log #debugging #debug #claude #cursor #windsurf #opencode #codex #cline #ai-tools

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "tmux": {
      "command": "tmux-mcp"
    }
  }
}

Tools

No tools detected

We auto-extract tools from the README. The maintainer can list them under a ## Tools heading to populate this section.

Overview

What is tmux-mcp?

tmux-mcp is an MCP server that gives AI assistants full visibility into your tmux sessions — browse sessions, windows, and panes, read terminal output, and send commands. It works with Claude Code, OpenCode, Cursor, Windsurf, and any MCP‑compatible host. Optionally, it can route all shell commands through a named tmux session for live auditing.

How to use tmux-mcp?

Install globally with npm install -g @fr1sk/tmux-mcp, then add a local MCP server entry in your client’s config (OpenCode, Claude Code, Cursor/Windsurf). Use tools like list_sessions, capture_pane, send_keys, etc. Environment variables TMUX_MCP_ALWAYS_USE and TMUX_MCP_DEFAULT_SESSION control whether all shell commands are forced through tmux.

Key features of tmux-mcp

List all active tmux sessions with window count and status
Capture visible pane output with up to 5 000 lines of scrollback
Send shell commands or raw key sequences to any pane
Create, rename, split, and delete sessions / windows / panes
Error‑safe: returns readable messages instead of crashing on bad targets
Configurable wait time before capturing pane output after sending keys

Use cases of tmux-mcp

Browse tmux state and discover active sessions, windows, and panes
Read logs, compiler errors, server output, or test runs from a pane
Send commands (e.g., git status, npm test) and immediately read the result
Create new tmux sessions for projects and run commands in them
Route all AI‑driven shell commands through tmux for full auditability

FAQ from tmux-mcp

What MCP hosts are compatible with tmux-mcp?

Works with Claude Code, OpenCode, Cursor, Windsurf, and any MCP‑compatible host.

How do I target a specific pane for commands or capture?

Use tmux’s standard session:window.pane notation (e.g., work:0.0). Use list_sessions, list_windows, and list_panes to discover correct targets.

Can I force all AI shell commands to go through tmux?

Yes. Set the environment variable TMUX_MCP_ALWAYS_USE to "true" and optionally TMUX_MCP_DEFAULT_SESSION to a session name.

Frequently asked questions

What MCP hosts are compatible with tmux-mcp?

Works with Claude Code, OpenCode, Cursor, Windsurf, and any MCP‑compatible host.

How do I target a specific pane for commands or capture?

Use tmux’s standard `session:window.pane` notation (e.g., `work:0.0`). Use `list_sessions`, `list_windows`, and `list_panes` to discover correct targets.