tmux-mcp-claude
Provides tools for managing tmux sessions, windows, and panes, including sending keys, capturing output, creating and destroying panes/windows.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@tmux-mcp-claude list my tmux sessions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
tmux-mcp-claude
MCP server that gives Claude Code full control over tmux sessions, windows, and panes — plus an optional AI safety classifier that uses Claude Sonnet to gate destructive commands.
What's included
Component | Description |
| MCP server exposing 11 tmux tools |
| Desktop notification when Claude needs input |
| Re-injects tmux workspace state after context compaction |
Settings snippets (below) | Sonnet-based safety classifier for |
Related MCP server: Tmux MCP Server
Quick start
git clone <repo-url> ~/.claude/mcp-servers/tmux-mcp
cd ~/.claude/mcp-servers/tmux-mcp
npm installThen add the MCP server to your Claude Code settings (~/.claude/settings.json):
{
"mcpServers": {
"tmux": {
"command": "node",
"args": ["<path-to>/tmux-mcp-claude/server.mjs"]
}
}
}Restart Claude Code — the 11 tmux_* tools will appear automatically.
Tools
Listing
Tool | Description | Parameters |
| List all tmux sessions | (none) |
| List windows in a session |
|
| List panes in a window |
|
Sending commands and reading output
Tool | Description | Parameters |
| Send keys/command to a pane |
|
| Capture visible content of a pane |
|
Creating windows and panes
Tool | Description | Parameters |
| Create a new window |
|
| Split a pane |
|
Navigation and cleanup
Tool | Description | Parameters |
| Switch to a window |
|
| Switch to a pane |
|
| Kill a pane |
|
| Kill a window |
|
Target syntax
Tmux targets follow the format session:window.pane:
mysession— the sessionmysession:0— window 0mysession:0.1— pane 1 in window 0
Safety classifier hook (optional but recommended)
The MCP server itself has no guardrails — it will happily rm -rf / if asked. The safety comes from a PreToolUse hook that intercepts every tmux_send_keys call and uses Claude Sonnet to classify the command before it executes:
Safe commands (reads, builds, navigation) → auto-allowed, no prompt
Destructive commands (rm, kill, force-push, DROP, etc.) → asks for user permission
Setup
Add these sections to your ~/.claude/settings.json:
1. Auto-allow the tmux tools (so Claude doesn't ask permission for each call)
{
"permissions": {
"allow": [
"mcp__tmux__tmux_list_sessions",
"mcp__tmux__tmux_list_windows",
"mcp__tmux__tmux_list_panes",
"mcp__tmux__tmux_capture_pane",
"mcp__tmux__tmux_new_window",
"mcp__tmux__tmux_split_window",
"mcp__tmux__tmux_select_window",
"mcp__tmux__tmux_select_pane",
"mcp__tmux__tmux_kill_pane",
"mcp__tmux__tmux_kill_window",
"mcp__tmux__tmux_send_keys"
]
}
}2. Sonnet safety classifier (PreToolUse hook)
{
"hooks": {
"PreToolUse": [
{
"matcher": "mcp__tmux__tmux_send_keys",
"hooks": [
{
"type": "prompt",
"prompt": "You are a security classifier for tmux_send_keys. The tool input is: $ARGUMENTS\n\nExtract the \"keys\" field from tool_input. Classify the command that is about to be sent to a tmux pane.\n\nBLOCK (return permissionDecision: \"ask\") if the command would:\n- Delete files or directories (rm, rmdir, shred)\n- Overwrite or truncate files (>, tee without -a on important files)\n- Kill processes (kill, killall, pkill, xkill)\n- Modify system state dangerously (systemctl stop/disable, shutdown, reboot, halt)\n- Drop databases/tables or delete data (DROP, DELETE without WHERE, TRUNCATE)\n- Force-push, hard-reset, or destructive git ops (git push --force, git reset --hard, git clean -f, git checkout .)\n- Modify permissions broadly (chmod -R 777, chown -R)\n- Send mutating requests to external services (curl -X POST/PUT/DELETE/PATCH, wget --post)\n- Remove packages (dnf remove, apt remove/purge, pip uninstall)\n- Run anything else that is hard to reverse or could cause data loss\n\nALLOW (return permissionDecision: \"allow\") if the command:\n- Only reads data (ls, cat, grep, find, git status/log/diff, kubectl get/describe, oc get)\n- Runs builds or tests (make, go build/test, npm test/build, mvn, gradle)\n- Navigates (cd, pushd, popd)\n- Sets environment variables or exports\n- Echoes/prints output\n- Creates new files/dirs without overwriting (touch, mkdir -p)\n- Installs packages (generally reversible)\n- SSH, scp, rsync (read-like or additive)\n- Any other read-only or easily reversible operation\n\nRespond with a JSON object. For safe commands: {\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"allow\"}}. For destructive commands: {\"hookSpecificOutput\": {\"hookEventName\": \"PreToolUse\", \"permissionDecision\": \"ask\", \"permissionDecisionReason\": \"<brief reason>\"}}.",
"model": "claude-sonnet-4-6",
"statusMessage": "Classifying tmux command safety..."
}
]
}
]
}
}3. Optional companion hooks
Desktop notification when Claude stops and waits for input:
{
"hooks": {
"Stop": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "<path-to>/tmux-mcp-claude/hooks/notify-attention.sh"
}
]
}
]
}
}Re-inject tmux state after context compaction:
{
"hooks": {
"PostCompact": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "<path-to>/tmux-mcp-claude/hooks/tmux-compact-hook.sh"
}
]
}
]
}
}Security
server.mjsusesexecFile(no shell) — immune to command injectionArguments passed as arrays, never string-interpolated
Only calls tmux subcommands, no arbitrary shell execution
The Sonnet safety hook adds a semantic layer on top, catching destructive intent even in complex or piped commands
How it works
Claude Code ──▶ tmux_send_keys("rm -rf /tmp/old")
│
▼
PreToolUse hook fires
│
▼
Sonnet classifies: "destructive — file deletion"
│
▼
User prompted: "Allow rm -rf /tmp/old?"
│
┌────┴────┐
▼ ▼
Allow Deny
│
▼
tmux send-keys executesExample workflow
# Claude discovers your tmux sessions
tmux_list_sessions()
tmux_list_windows(session="work")
# Creates a window for a task
tmux_new_window(session="work", name="build")
# Runs a command (auto-allowed by Sonnet — it's a build)
tmux_send_keys(target="work:build", keys="make test")
# Reads the output
tmux_capture_pane(target="work:build")
# Tries something destructive (Sonnet asks permission)
tmux_send_keys(target="work:build", keys="rm -rf ./dist")
# → User prompted before executionToggle/disable
Action | How |
Disable all hooks |
|
Re-enable all hooks | Remove/set false |
Review hooks in UI |
|
Remove safety hook only | Delete the PreToolUse entry from settings.json |
License
MIT
Available Tools
11 toolstmux_capture_paneA
Capture the visible content of a tmux pane (what you'd see on screen).
Inputs: target (required), end, start.
tmux_kill_paneB
Kill a tmux pane.
Inputs: target (required).
tmux_kill_windowB
Kill a tmux window.
Inputs: target (required).
tmux_list_panesA
List panes in a tmux window or session
Inputs: target.
tmux_list_sessionsA
List all tmux sessions
Inputs: no named parameters.
tmux_list_windowsA
List windows in a tmux session
Inputs: session.
tmux_new_windowB
Create a new window in a tmux session.
Inputs: name, command, session.
tmux_select_paneC
Switch to a pane.
Inputs: target (required).
tmux_select_windowC
Switch to a window.
Inputs: target (required).
tmux_send_keysA
Send keys or a command to a tmux pane. Appends Enter by default.
Inputs: keys (required), target (required), enter.
tmux_split_windowB
Split a pane to create a new pane.
Inputs: target, command, percent, horizontal.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool clearly targets a distinct tmux resource and action: sessions, windows, panes with list, create, select, kill, send, capture. There is no overlap in purpose, and descriptions reinforce the boundaries.
All tools follow the exact `tmux_verb_noun` pattern, with verbs like list, send, capture, new, split, select, kill. The naming is perfectly uniform and predictable.
With 11 tools, the server covers the core tmux operations without bloat. Every tool handles a distinct operation, making the set feel well-scoped and purposeful.
The set covers listing sessions/windows/panes, creating windows, splitting panes, sending keys, capturing output, selecting windows/panes, and killing panes/windows. Missing session-level operations like kill session or rename are minor gaps that can be worked around via existing tools.
Maintenance
Related MCP Connectors
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables Claude Desktop to interact with and view tmux session content, allowing AI assistants to read from, control, and observe terminal sessions.13382 npm307MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to manage local tmux sessions, including creating and controlling sessions, windows, and panes, sending commands, and capturing terminal output.1614 npmDo What The F*ck You Want To Public
- AlicenseNot gradedqualityDmaintenanceEnables Claude to execute commands and manage directory-aware panes within tmux sessions for a shared terminal experience. It features smart output capture, interactive prompt detection, and background task management.2MIT
- FlicenseNot gradedqualityDmaintenanceExposes tmux features to AI agents for managing sessions, windows, and panes with built-in command execution. It includes comprehensive guardrails to prevent destructive system operations, file deletions, and unauthorized network changes.-