Terminal MCP

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

---

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.

uvx terminal-mcp

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

---

Quick Start

1. Install (30 seconds)

# 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:

{

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

Claude Desktop

Add to claude_desktop_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:

{

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

Windsurf

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

{

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

3. Verify

session_exec  exec="echo hello from terminal-mcp"

---

What Can You Do With It?

SSH Into Remote Servers

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

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

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

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

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

session_exec  exec="git log --oneline -10"

session_exec exec="docker compose ps" timeout=10

---

Features at a Glance

---

Tools Reference

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

---

Architecture

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.

Example with custom settings:

{

"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

---

Supported Clients

---

Running Tests

pip install -e ".[dev]"

pytest tests/ -v

Contributing

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

License

MIT