# terminal-mcp [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/mkpvishnu/terminal-mcp  
**GitHub Stars:** 12  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/terminal-mcp

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

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## What terminal-mcp MCP server does

The terminal-mcp MCP server exposes terminal sessions to an MCP-compatible AI client. Sessions remain available across tool calls, allowing an agent to start a shell, SSH connection, Python interpreter, database CLI, or terminal user interface and continue working in the same process.

It also supports commands that do not need a persistent session. The `session_exec` tool runs a single command, while session tools cover creation, input, output, waiting, resizing, listing, and cleanup. This makes the server suitable for workflows where ordinary isolated command execution loses shell state or cannot handle interactive programs.

## How it works

Each session uses a real pseudo-terminal. On supported Unix-like systems, the implementation uses `pexpect.spawn`; on Windows, it uses `PopenSpawn`. The server manages multiple PTYs and exposes them through MCP JSON-RPC between the client and server.

Output can be read as a stream, a terminal snapshot, automatically selected output, or a diff containing changed screen lines. Pattern-based waiting uses a regular expression, so an agent can wait for a prompt or build result instead of relying only on fixed delays. `session_interact` combines sending input and reading output in one operation.

The server includes handling for special keys, control characters, terminal resizing, idle-session cleanup, output truncation, secret input, and a dangerous-command confirmation gate.

## Setup and configuration

Python 3.10 or newer is required. The quickest launch method is:

```bash
uvx terminal-mcp
```

Alternatively, install the package with `pip install terminal-mcp`. An MCP client configuration points to the `uvx` command with `terminal-mcp` as its argument. The README provides configurations for Claude Code, Claude Desktop, VS Code, Cursor, and Windsurf.

Settings are configurable through `TERMINAL_MCP_*` environment variables.

## Tools and capabilities

The terminal-mcp MCP server provides nine tools:

- `session_create` starts a persistent terminal session.
- `session_send` sends text, keys, or control characters.
- `session_read` reads stream, snapshot, automatic, or diff output.
- `session_interact` sends input and reads output together.
- `session_wait_for` waits for a regular-expression match.
- `session_exec` runs a one-off command.
- `session_close` closes a session.
- `session_resize` changes terminal dimensions.
- `session_list` lists active sessions.

These capabilities cover remote SSH work, interactive Python or other REPL sessions, database CLIs such as `psql`, TUI navigation with function and arrow keys, and monitoring commands such as builds or log watchers.

## Limitations and notes

The server gives an agent access to terminal commands and interactive processes, so the commands available to it depend on the local machine and any remote systems reached through SSH. The README specifically notes a dangerous-command gate for examples including `rm -rf`, `DROP TABLE`, and `curl|sh`; such commands require confirmation. Session resources also remain subject to the configured session limit and idle cleanup behavior.

_Full upstream README: https://allmcps.com/mcp/terminal-mcp/readme_