Terminal MCP Server
Allows managing multiplexed terminal sessions via tmux, enabling spawning, sending input, reading output, and orchestrating multiple concurrent terminal sessions.
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., "@Terminal MCP Server spawn a background session named 'server' running 'npm run dev'"
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.
Terminal MCP Server
MCP server for managing multiplexed terminal sessions via tmux. Lets AI agents spawn, send input to, read output from, and orchestrate multiple concurrent terminal sessions.
Why
Claude Code (and other MCP clients) can run shell commands, but can't manage long-running processes, interactive sessions, or multiple concurrent terminals. This server bridges that gap using tmux as the multiplexer.
Key use case: multi-agent orchestration. Run multiple Claude Code sessions in tmux panes, then use terminal_send to type messages into any session — from the target's perspective, a human just typed. This enables Claude-to-Claude communication with full context and permissions.
Related MCP server: Agent Collaboration MCP Server
Install
Requires tmux installed and in PATH.
Add to your Claude Code MCP config (~/.claude/mcp.json or .mcp.json):
{
"mcpServers": {
"terminal": {
"command": "npx",
"args": ["@quantum-encoding-europe-limited/terminal-mcp"]
}
}
}Or run directly:
npx @quantum-encoding-europe-limited/terminal-mcpTools
Tool | Description |
| List all active sessions (name, PID, cwd, command) |
| Create a named session with optional cwd, startup command, and mode |
| Type text into a session (keystrokes via tmux send-keys) |
| Read last N lines from a session (ANSI-stripped) |
| Graceful close (Ctrl+C, Ctrl+D, then kill) |
| Send Ctrl+C/D/Z/L/\ to a session |
| Resize pane dimensions |
| Overview of ALL sessions — last 5 lines each |
| Poll until output matches a pattern (e.g. "Server ready") |
Spawn Modes
terminal_spawn supports a mode parameter for controlling how Claude sessions run:
Mode | Behaviour |
| (default) Normal foreground session with permission prompts. Best when you need to approve tool calls. |
| Auto-allows safe tools (Bash, Edit, Read, Write, Glob, Grep, Agent) but blocks destructive ops (git force push, git reset --hard, git branch -D, git clean -f, rm -rf). Best for autonomous work with guardrails. |
| Resume an existing Claude session by name, with the same background safety guardrails. |
terminal_spawn("scanner", cwd="/my/project", mode="background")
// Launches: claude --allowedTools "Bash(*) Edit Read Write Glob Grep Agent"
// --disallowedTools "Bash(git push --force*) Bash(git reset --hard*) ..."
terminal_spawn("scanner", mode="resume")
// Launches: claude --resume "scanner" --allowedTools ... --disallowedTools ...Note: Background mode never uses --dangerously-skip-permissions. It uses curated allow/deny lists so agents can work autonomously without being able to force-push, delete branches, or wipe files.
Examples
Run a dev server and wait for it
terminal_spawn("server", cwd="/my/project", command="npm run dev")
terminal_wait("server", pattern="ready on port 3000")Orchestrate multiple Claude sessions
# Spawn specialists in background mode (no permission prompts)
terminal_spawn("backend", cwd="/work/api", mode="background")
terminal_spawn("frontend", cwd="/work/app", mode="background")
# Wait for Claude to start, then send tasks
terminal_wait("backend", pattern="? for shortcuts")
terminal_send("backend", "add input validation to the POST /users endpoint")
terminal_wait("frontend", pattern="? for shortcuts")
terminal_send("frontend", "update the user form to match the new API validation")Monitor everything at once
terminal_snapshot() # see last 5 lines from every sessionConfiguration
Environment variables:
Variable | Default | Description |
| auto-detected / | tmux session name |
|
| Default line capture limit |
If running inside tmux, the current session is auto-detected. Otherwise falls back to TERMINAL_MCP_SESSION or creates mcp-terminals.
How it works
All terminal management goes through tmux:
terminal_spawn→tmux split-window+tmux select-pane -Tterminal_send→tmux send-keys(short input) ortmux load-buffer+paste-buffer(long input, avoids escaping issues)terminal_read→tmux capture-pane -pterminal_close→tmux kill-pane
Name matching is fuzzy — handles tmux title prefixes (like Claude's spinner characters ✳ ✽ ⏺) automatically.
License
MIT
Available Tools
9 toolsterminal_closeA
Close a terminal session by name. Sends SIGTERM to the process running in the pane.
Inputs: name (required), force.
terminal_listA
List all active terminal sessions with their names, PIDs, working directories, and current commands.
Inputs: no named parameters.
terminal_readA
Read the current visible output from a terminal session. Returns the last N lines of output with ANSI codes stripped.
Inputs: name (required), lines.
terminal_resizeA
Resize a terminal pane (useful before reading output from width-sensitive programs).
Inputs: name (required), width, height.
terminal_sendB
Send input (keystrokes) to a named terminal session. Use this to type commands, answer prompts, or send signals.
Inputs: name (required), input (required), enter.
terminal_send_signalA
Send a signal to a terminal session (Ctrl+C to interrupt, Ctrl+Z to suspend, Ctrl+D to EOF, etc).
Inputs: name (required), signal (required).
terminal_snapshotA
Take a snapshot of all terminals — names, commands, last few lines of output. Useful for getting an overview of what's happening across all sessions.
Inputs: no named parameters.
terminal_spawnA
Spawn a new named terminal session. Optionally start it in a specific directory and/or run a command immediately.
Use 'mode' to control how Claude sessions run:
"interactive" (default): Normal foreground session with permission prompts.
"background": Auto-allows safe tools (Bash, Edit, Read, Write, Glob, Grep, Agent) but blocks destructive git commands (force push, reset --hard, branch -D, clean -f) and rm -rf. Best when you want autonomous work with guardrails.
"resume": Resume an existing Claude session by name with the same background safety guardrails.
Inputs: name (required), cwd, mode, shell, +1 more.
terminal_waitA
Wait for a terminal to show specific output. Polls every second up to the timeout.
Also watches for permission prompts ("Do you want to proceed") and returns immediately with a "permission_needed" status so the conductor can approve without wasting the timeout.
Returns JSON-like status: "found" (pattern matched), "permission_needed" (prompt detected), or "timeout" (neither matched in time).
Inputs: name (required), pattern (required), timeout, interrupt_on.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool targets a distinct terminal operation: lifecycle (spawn/list/close), I/O (read/send/signal), and inspection (snapshot/resize/wait). Snapshot differs from list and read by combining an overview of all sessions with recent output. There is no real ambiguity between tools.
All tool names follow a consistent terminal_verb pattern: spawn, list, read, send, send_signal, resize, snapshot, wait, close. Even the compound send_signal is clearly a verb_noun construction consistent with the rest. The naming is uniform and predictable.
Nine tools is well-scoped for a terminal management server. Each tool covers a meaningful part of the terminal lifecycle without unnecessary redundancy. The count feels complete and not bloated.
The surface covers the full terminal workflow: spawn, interact, read, signal, resize, wait for output, snapshot, and close. There are no obvious missing operations that would prevent an agent from driving a terminal session effectively. The inclusion of permission-prompt handling in terminal_wait rounds out practical needs.
Maintenance
Related MCP Connectors
Docs for agent-manager, the terminal UI that runs AI coding agents as live tmux sessions.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to manage local tmux sessions, including creating and controlling sessions, windows, and panes, sending commands, and capturing terminal output.167 npmDo What The F*ck You Want To Public
- AlicenseBqualityDmaintenanceEnables AI agents to orchestrate a team of sub-agents through tmux sessions for complex task delegation and parallel implementation. It provides tools for launching agents, monitoring their real-time status, and managing communication between them.656 npm26MIT
- AlicenseAqualityDmaintenanceAllows AI assistants to create, manage, and interact with tmux sessions, windows, and panes programmatically.1928 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to execute commands in a shared tmux session that is simultaneously visible to a human via a web-based terminal UI.1MIT