Terminal MCP README

Give your AI a real terminal. Persistent sessions. Interactive programs. Zero limitations.

terminal-mcp demo

The Problem

Every AI coding tool hits the same wall: no real terminal access.

Claude Code's Bash tool, GitHub Copilot, and Codex all run commands in isolated subprocesses. Each command starts fresh. No state carries over. That means:

No SSH sessions - Can't connect to a remote server and run multiple commands
No REPLs - Can't use Python, Node, or Ruby interpreters interactively
No database CLIs - Can't maintain a psql, mysql, or redis-cli connection
No TUI apps - Can't navigate htop, vim, or fzf with arrow keys
No long-running processes - Can't monitor builds, watch logs, or run dev servers

The Solution

terminal-mcp gives AI agents a real terminal. Persistent PTY sessions that survive across tool calls. Send commands, read output, press keys, navigate TUIs - exactly like a human at a terminal.

Code

uvx terminal-mcp

One command. Works with Claude Code, Claude Desktop, VS Code, Cursor, and Windsurf.

Quick Start

1. Install (30 seconds)

bash

# No install needed - run directly
uvx terminal-mcp

# Or install globally
pip install terminal-mcp

2. Connect to Your AI Client

Claude Code

Add to ~/.claude.json or project .mcp.json:

config.json

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

config.json

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

VS Code / Cursor

Click the one-click install badge above, or add to .vscode/mcp.json:

config.json

{
  "servers": {
    "terminal-mcp": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

config.json

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

3. Verify

Code

session_exec  exec="echo hello from terminal-mcp"

What Can You Do With It?

SSH Into Remote Servers

Code

session_create   command="ssh user@prod-server.com"   label="prod"
session_interact session_id="a1b2c3d4"  input="df -h"  wait_for="\$"
session_interact session_id="a1b2c3d4"  input="docker ps"  wait_for="\$"
session_close    session_id="a1b2c3d4"

Run Interactive REPLs

server.ts

session_create   command="python3"  label="python"
session_interact session_id="e5f6g7h8"  input="import pandas as pd"  wait_for=">>>"
session_interact session_id="e5f6g7h8"  input="df = pd.read_csv('data.csv')"  wait_for=">>>"
session_interact session_id="e5f6g7h8"  input="df.describe()"  wait_for=">>>"
session_close    session_id="e5f6g7h8"

Query Databases

Dockerfile

session_create   command="psql -U admin mydb"  label="db"
session_interact session_id="x1y2z3w4"  input="SELECT count(*) FROM users;"  wait_for="row"
session_interact session_id="x1y2z3w4"  input="\dt"  wait_for="#"
session_close    session_id="x1y2z3w4"

Navigate TUI Apps

Code

session_create   command="htop"  label="monitor"
session_read     session_id="a1b2c3d4"
# Auto-detects TUI, returns screen snapshot

session_send     session_id="a1b2c3d4"  key="F6"
session_read     session_id="a1b2c3d4"  mode="diff"
# Returns only changed lines - saves tokens

session_send     session_id="a1b2c3d4"  key="F10"
session_close    session_id="a1b2c3d4"

Monitor Long-Running Builds

Code

session_create   command="bash"  label="build"
session_send     session_id="a1b2c3d4"  input="npm run build"
session_wait_for session_id="a1b2c3d4"  pattern="Build complete|ERROR"  timeout=120

Run One-Off Commands

Code

session_exec  exec="git log --oneline -10"
session_exec  exec="docker compose ps"  timeout=10

Features at a Glance

Feature	What It Does
Persistent Sessions	Real PTY sessions that survive across tool calls
Send + Read in One Call	`session_interact` halves LLM round trips
Pattern-Based Reads	`wait_for` blocks until regex matches - no guessing timeouts
Auto TUI Detection	Detects htop, vim, etc. and auto-switches to screen snapshot mode
Output Diff Mode	Returns only changed screen lines - minimizes tokens
Special Keys	Arrow keys, Tab, F1-F12, Home/End, Page Up/Down
Control Characters	Ctrl-C, Ctrl-D, Ctrl-Z, Ctrl-L, telnet escape
Dangerous Command Gate	Blocks `rm -rf`, `DROP TABLE`, `curl\|sh` - requires confirmation
OSC 133 Shell Integration	Auto-detects command boundaries and exit codes
Smart Truncation	Four strategies to prevent context overflow
Secret Input	Send passwords without logging
Dynamic Resize	Resize terminal on the fly with SIGWINCH
Idle Cleanup	Auto-closes idle sessions
Cross-Platform	Linux, macOS, and Windows support

Tools Reference

terminal-mcp exposes 9 MCP tools. Full details in docs/tools.md.

Tool	Purpose
`session_create`	Spawn a persistent terminal session
`session_send`	Send text, keys, or control characters
`session_read`	Read output (stream, snapshot, auto, diff modes)
`session_interact`	Send + read in one call
`session_wait_for`	Wait for regex pattern in output
`session_exec`	One-shot command execution
`session_close`	Close a session gracefully
`session_resize`	Resize terminal dimensions
`session_list`	List active sessions

Architecture

mermaid

flowchart LR
    Client[AI Client] -->|MCP JSON-RPC| Server[terminal-mcp]
    Server --> SM[Session Manager]
    SM --> S1[PTY 1: bash]
    SM --> S2[PTY 2: python3]
    SM --> S3[PTY 3: ssh user@host]
    S1 & S2 & S3 -.->|PTY output| Reader[Reader Thread]
    Reader -.->|buffer| Server

Each session is backed by a real PTY via pexpect.spawn (or PopenSpawn on Windows). For full architecture details, see docs/architecture.md.

Configuration

All settings configurable via TERMINAL_MCP_* environment variables. Full reference in docs/configuration.md.

Setting	Env Var	Default
Max sessions	`TERMINAL_MCP_MAX_SESSIONS`	`10`
Idle timeout	`TERMINAL_MCP_IDLE_TIMEOUT`	`1800` (30 min)
Safety gate	`TERMINAL_MCP_SAFETY_GATE`	`on`
Buffer cap	`TERMINAL_MCP_MAX_BUFFER_BYTES`	`1000000` (1MB)
Truncation	`TERMINAL_MCP_TRUNCATION_MODE`	`tail`

Example with custom settings:

config.json

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"],
      "env": {
        "TERMINAL_MCP_MAX_SESSIONS": "20",
        "TERMINAL_MCP_IDLE_TIMEOUT": "3600",
        "TERMINAL_MCP_TRUNCATION_MODE": "head_tail"
      }
    }
  }
}

Documentation

Document	Description
Tools Reference	Complete API for all 9 MCP tools
Architecture	How terminal-mcp works under the hood
Configuration	All settings and environment variables
Safety & Security	Dangerous command detection and safety gate
Use Cases & Examples	Real-world recipes and patterns
Changelog	Version history and release notes
Contributing	How to contribute

Supported Clients

Client	Status	Install
Claude Code (CLI)	Supported	`~/.claude.json` or `.mcp.json`
Claude Desktop	Supported	One-click install
VS Code (Copilot Chat)	Supported	One-click install or `.vscode/mcp.json`
Cursor	Supported	One-click install or Settings
Windsurf	Supported	`~/.codeium/windsurf/mcp_config.json`

Running Tests

Terminal

pip install -e ".[dev]"
pytest tests/ -v

Contributing

Contributions welcome! See docs/contributing.md for guidelines.

License

MIT