Terminal MCP

MCP server for interactive terminal sessions — SSH, REPLs, database CLIs, TUI apps

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Databases View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Terminal MCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "terminal-mcp": { "command": "npx", "args": ["-y", "terminal-mcp"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/terminal-mcp?style=directory)](https://allmcps.com/mcp/terminal-mcp)

HTML Embed

<a href="https://allmcps.com/mcp/terminal-mcp"><img src="https://allmcps.com/api/badge/terminal-mcp?style=directory" alt="Terminal MCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryDatabases

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

A guidance signal from public completeness & health data — not a user rating. New listings start lower and rise as they add docs, get verified, and grow adoption. Signals we can't observe for a listing are skipped, not counted against it.

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

This directory is pre-filled from public sources. Claim via GitHub README, site badge, or DNS TXT to unlock edit access and the Official badge and attach your website — proof is checked automatically, then reviewed by our team.

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🗄️ Databases →Best MCP servers for Databases →Alternatives to Terminal MCP →Install in Claude Desktop Install in Cursor Install in VS Code

Terminal MCP

MCP server for interactive terminal sessions — SSH, REPLs, database CLIs, TUI apps

Quick Install

Automated & IDE Setup

Copy the AI prompt to install this server into Claude Code, Cursor, or another agent — or use 1-click editor setup below.

Add to Cursor Add to VS Code

Manual Client & Custom JSON ConfigExpand JSON ▾

Client Config & Setup

Choose your client or environment

Target File:~/Library/Application Support/Claude/claude_desktop_config.json

claude_desktop_config.json

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

💡 Paste the JSON block into your client's configuration file under mcpServers, then restart the application.

Documentation Overview

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

Read the full README →View source on GitHub →

Related MCP Servers

View all in Databases View all alternatives

Reviews

No reviews yet — be the first to share how this listing worked for you.

Frequently Asked Questions about Terminal MCP

Add the following block to your claude_desktop_config.json under mcpServers: "mcpServers": { "terminal-mcp": { "command": "npx", "args": ["-y", "terminal-mcp"] } }

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:

Live Dynamic SVG Preview

Markdown (GitHub README)

[![AllMCPs](https://allmcps.com/api/badge/terminal-mcp?style=directory)](https://allmcps.com/mcp/terminal-mcp)

HTML Embed

<a href="https://allmcps.com/mcp/terminal-mcp"><img src="https://allmcps.com/api/badge/terminal-mcp?style=directory" alt="Terminal MCP on AllMCPs" /></a>

Technical Specs & Signals

CategoryDatabases

27Quality signal: Emerging · 27/100How this signal is calculated ▾

Server availabilityNot measured

Not scored for repo-hosted servers — we can't reach the running server, only its GitHub page. Hosted MCP endpoints are health-checked live.

Verified ownership8/20

Documentation & tools11/30

Adoption & activity1/15

Community engagement0/10

★ Featured

Moxie Docs MCP

MCP & Agent Skills for Automated Documentation, and codebase conventions + context

Explore Server →

Own this project?

Free dofollow backlink: add your website and place the AllMCPs badge on it — no claim needed. We detect it automatically and keep it verified as long as the badge stays live.

Claim & get free dofollow

Share & Embed

Add our SVG badge (dark/light directory styles) or embeddable widget to your site.

Explore more

More in 🗄️ Databases →Best MCP servers for Databases →Alternatives to Terminal MCP →Install in Claude Desktop Install in Cursor Install in VS Code