# nvms/tui-mcp [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/nvms/tui-mcp  
**GitHub Stars:** 14  
**npm Downloads (last month):** 118  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/nvms-tui-mcp

## Description
What Chrome DevTools MCP is for the browser, tui-mcp is for the terminal. Launch, screenshot, and interact with any TUI app.

## Tools
Capabilities this server exposes over MCP:

- **launch** — Spawn a TUI app in a managed pty
- **kill** — Terminate a session
- **list_sessions** — List sessions, including recently exited ones
- **status** — Get one session's state and exit code
- **resize** — Resize the terminal
- **screenshot** — Capture terminal as PNG
- **snapshot** — Capture terminal as plain text
- **scrollback** — Read the buffer including scrolled-off history
- **output** — Read the raw pty byte stream (escape sequences included)
- **read_region** — Read a rectangular area of the buffer
- **cursor** — Get cursor position
- **send_keys** — Send a keystroke or combo (`Enter`, `Ctrl+C`, `Ctrl+Up`, `q`)
- **send_text** — Type a string of characters
- **send_mouse** — Send mouse events
- **wait_for_text** — Wait for a regex pattern to appear
- **wait_for_idle** — Wait until the terminal stops changing
- **wait_for_exit** — Wait for the process to exit and get its exit code

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

```json
"mcpServers": {
  "tui-mcp": {
    "command": "npx",
    "args": ["-y","tui-mcp"]
  }
}
```

## Documentation

## What nvms/tui-mcp does

The nvms/tui-mcp MCP server gives an agent a persistent terminal session for launching and operating command-line applications. Each application runs in a managed pseudo-terminal, so it can behave as if a person opened a real terminal. This supports full-screen interfaces and interactive programs, including applications built with different TUI frameworks or with no framework.

Unlike a one-shot shell command, a session remains available across MCP calls. That makes it possible to preserve state in programs such as database shells, continue through multi-step prompts, watch a long-running process, or work inside an interactive editor or debugger. The server does not target one product API; it exposes the terminal interaction layer used by many command-line programs.

## How it works

The application runs through node-pty, which provides a pseudo-terminal configured with `xterm-256color`. Terminal output is parsed by xterm-headless, allowing the server to expose the resulting buffer to MCP tools. The flow is application to pseudo-terminal to terminal emulator to MCP operations.

The nvms/tui-mcp MCP server can return a rendered PNG, plain terminal text, scrolled-off history, a selected rectangular region, cursor coordinates, or the unprocessed pty byte stream. Input can be sent as individual keys or combinations, text, and mouse events. Waiting tools can pause until a regular expression appears, the terminal becomes idle, or the process exits.

## Setup and configuration

The README provides this Claude MCP setup command:

```bash
claude mcp add --scope user tui-mcp -- npx tui-mcp
```

The package is started with `npx tui-mcp`. A separate terminal monitor can be started with:

```bash
npx tui-mcp monitor
```

The monitor discovers running tui-mcp servers on the machine and displays their sessions with a live ANSI-rendered preview. It can attach to sessions, launch new ones, show scrollback, and terminate selected sessions. Attach, launch, kill, and scrollback require server version 1.2 or newer; older sessions can still be observed in read-only mode.

## Tools and capabilities

The server exposes tools for the complete session lifecycle:

- `launch`, `kill`, `list_sessions`, and `status` manage processes and report session state or exit codes.
- `resize` changes terminal dimensions.
- `screenshot`, `snapshot`, `scrollback`, `output`, `read_region`, and `cursor` inspect terminal contents and position.
- `send_keys`, `send_text`, and `send_mouse` provide keyboard, text, and pointer input.
- `wait_for_text`, `wait_for_idle`, and `wait_for_exit` coordinate actions with terminal or process state.

## Limitations and notes

The nvms/tui-mcp MCP server provides terminal-level interaction rather than a specialized integration for a particular CLI, database, cloud platform, or operating system service. The target application must be available in the environment where the server runs. Raw pty output includes escape sequences, while rendered or text-oriented inspection is available through separate tools. Session control and observation depend on the server version noted above.

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