Log inSubmit server
Terminal MCP logo

Terminal MCP

Provides persistent PTY sessions for SSH, REPLs, database CLIs, TUI apps, and one-off terminal commands.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Terminal MCP

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "terminal-mcp": {
      "command": "uvx",
      "args": [
        "terminal-mcp"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

The terminal-mcp MCP server gives AI clients persistent terminal sessions backed by real PTYs. It supports SSH connections, interactive interpreters, database command-line clients, TUI applications, long-running processes, and one-shot commands through MCP tools. Use it when isolated subprocesses cannot preserve state between commands or when an agent needs to send keys and read interactive output. It runs through stdio with uvx or an installed Python package and is documented for Claude Code, Claude Desktop, VS Code, Cursor, and Windsurf.

Use cases

  • Maintain an SSH session across multiple commands
  • Run an interactive Python, Node, or Ruby REPL
  • Query a database through a persistent CLI connection
  • Navigate TUI applications with keys and screen snapshots
  • Monitor long-running builds or development processes

Key features

  • Persistent PTY sessions
  • Interactive SSH, REPL, database CLI, and TUI support
  • Pattern-based output waiting
  • TUI snapshots and diff output
  • Special keys and control-character input
  • Dangerous-command confirmation gate

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

7/7 checks healthy over the last 41d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 14d ago via OSV.dev · terminal-mcp (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars12Stargazers on the source repository.
Last commit2mo agoMost recent push to the default branch.

How Terminal MCP works

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.

Read the full README View source on GitHub

Reviews

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

Frequently Asked Questions about Terminal MCP

terminal-mcp is an MCP server that connects AI clients to real persistent PTY sessions for local shells and interactive programs, including SSH, REPLs, database CLIs, and TUIs. Its main tools create, send input to, read from, wait on, resize, list, execute commands in, and close terminal sessions.

Run `uvx terminal-mcp` without installing it, or install the package with `pip install terminal-mcp`. Then add an MCP server entry that invokes `uvx` with `terminal-mcp` as its argument.

Yes, terminal-mcp works with Cursor. You can use the documented one-click install option or add a server entry to `.vscode/mcp.json` with `uvx` and `terminal-mcp`.

Yes, terminal-mcp can keep an SSH session open across tool calls. Create a session with an SSH command, interact with it using `session_interact` or other session tools, and close it with `session_close`.

terminal-mcp provides nine tools: `session_create`, `session_send`, `session_read`, `session_interact`, `session_wait_for`, `session_exec`, `session_close`, `session_resize`, and `session_list`.

Related MCP servers

All in Databases All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

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 PreviewTerminal MCP AllMCPs Directory Badge
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>