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.

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-mcp

Tools

Tool	Description
terminal_list	List all active sessions (name, PID, cwd, command)
terminal_spawn	Create a named session with optional cwd, startup command, and mode
terminal_send	Type text into a session (keystrokes via tmux send-keys)
terminal_read	Read last N lines from a session (ANSI-stripped)
terminal_close	Graceful close (Ctrl+C, Ctrl+D, then kill)
terminal_send_signal	Send Ctrl+C/D/Z/L/\ to a session
terminal_resize	Resize pane dimensions
terminal_snapshot	Overview of ALL sessions — last 5 lines each
terminal_wait	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
interactive	(default) Normal foreground session with permission prompts. Best when you need to approve tool calls.
background	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	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 session

Configuration

Environment variables:

Variable	Default	Description
TERMINAL_MCP_SESSION	auto-detected / mcp-terminals	tmux session name
TERMINAL_MCP_MAX_LINES	200	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 -T
• terminal_send → tmux send-keys (short input) or tmux load-buffer + paste-buffer (long input, avoids escaping issues)
• terminal_read → tmux capture-pane -p
• terminal_close → tmux kill-pane

Name matching is fuzzy — handles tmux title prefixes (like Claude's spinner characters ✳ ✽ ⏺) automatically.

License

MIT