Terminal Mcp

[terminal-mcp banner]

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

[PyPI] [Python 3.10+] [License: MIT] [CI] [CodeQL]

[Install in VS Code] [Install in VS Code Insiders] [Install in Cursor] [Install in Claude Desktop]

[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.

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 directlyuvx terminal-mcp
# Or install globallypip install terminal-mcp

2. Connect to Your AI Client

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

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

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

{  "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 [email protected]"   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