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

Tools

Spawn Modes

terminal_spawn supports a mode parameter for controlling how Claude sessions run:

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:

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