# terminal-mcp

Gives an AI agent persistent terminal sessions for SSH, REPLs, database CLIs, and TUI apps. Useful when commands need to share state.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 12
- Author: mkpvishnu
- License: MIT · policy=link-only · description only; the file stays with the author
- Source: https://github.com/mkpvishnu/terminal-mcp
- Updated: 2026-08-17
- HTML: https://affpapa.org/en/nevibecode/mcp/terminal-mcp

## What it does

terminal-mcp exposes persistent PTY sessions that remain available across tool calls. An agent can submit commands, inspect output, send keys, and interact with programs that expect a live terminal. Its tools include `session_create`, `session_interact`, `session_read`, `session_send`, `session_wait_for`, `session_exec`, and `session_close`.

The server supports SSH connections, Python REPL work, `psql` queries, TUI navigation, and waiting for a build to match a completion or error pattern. Diff reads return changed screen lines, while risky commands require confirmation. Running it through `uvx` requires Python 3.10+.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Environment variables: `TERMINAL_MCP_MAX_SESSIONS`, `TERMINAL_MCP_IDLE_TIMEOUT` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env TERMINAL_MCP_MAX_SESSIONS=<TERMINAL_MCP_MAX_SESSIONS> --env TERMINAL_MCP_IDLE_TIMEOUT=<TERMINAL_MCP_IDLE_TIMEOUT> --transport stdio terminal-mcp -- uvx terminal-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add terminal-mcp --env TERMINAL_MCP_MAX_SESSIONS=<TERMINAL_MCP_MAX_SESSIONS> --env TERMINAL_MCP_IDLE_TIMEOUT=<TERMINAL_MCP_IDLE_TIMEOUT> -- uvx terminal-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "terminal-mcp": {
            "command": "uvx",
            "args": [
                "terminal-mcp"
            ],
            "env": {
                "TERMINAL_MCP_MAX_SESSIONS": "<TERMINAL_MCP_MAX_SESSIONS>",
                "TERMINAL_MCP_IDLE_TIMEOUT": "<TERMINAL_MCP_IDLE_TIMEOUT>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "terminal-mcp": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "terminal-mcp"
            ],
            "env": {
                "TERMINAL_MCP_MAX_SESSIONS": "<TERMINAL_MCP_MAX_SESSIONS>",
                "TERMINAL_MCP_IDLE_TIMEOUT": "<TERMINAL_MCP_IDLE_TIMEOUT>"
            }
        }
    }
}
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e TERMINAL_MCP_MAX_SESSIONS=<TERMINAL_MCP_MAX_SESSIONS> -e TERMINAL_MCP_IDLE_TIMEOUT=<TERMINAL_MCP_IDLE_TIMEOUT> terminal-mcp uvx terminal-mcp
```
Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from terminal-mcp <command>

## When to use it
- keep an SSH connection across commands
- run code inside an interactive Python REPL
- maintain a database CLI session
- control a TUI app with key presses
- wait for a long build to finish by pattern

## Example prompts
- Connect to the server over SSH, create a session labeled `prod`, run `df -h`, and then show the result of `docker ps`.
- Open a persistent Python session, load `data.csv` with pandas, and print a summary of the table.
- Start `npm run build` in a separate session and wait for `Build complete|ERROR` for up to 120 seconds.

## Similar
- [interactive-terminal](https://affpapa.org/en/nevibecode/mcp/interactive-terminal.md) — MCP server · ★ 19
- [terminal-control](https://affpapa.org/en/nevibecode/skills/terminal-control.md) — skill · 505 installs
- [sheets-terminal-spreadsheet](https://affpapa.org/en/nevibecode/skills/sheets-terminal-spreadsheet.md) — skill · 726 installs
- [cmux-terminal-multiplexer](https://affpapa.org/en/nevibecode/skills/cmux-terminal-multiplexer.md) — skill · 1400 installs
- [terminal-ui](https://affpapa.org/en/nevibecode/skills/terminal-ui.md) — skill · 836 installs
- [monitoring-terminal-errors](https://affpapa.org/en/nevibecode/skills/monitoring-terminal-errors.md) — skill · 449 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md