io.github.mkpvishnu/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