nvms/tui-mcp

What Chrome DevTools MCP is for the browser, tui-mcp is for the terminal.

Launch any terminal app in a managed pty, take screenshots, read text, send keystrokes. The app thinks it's running in a real terminal. Works with any TUI framework or no framework at all - vim, htop, bubbletea, textual, ink, inquirer, trend, ncurses, whatever.

How is this different from a bash tool?

A bash tool runs discrete commands - each invocation is fire-and-forget. The process exits, the output comes back. tui-mcp maintains a persistent, interactive session. The pty stays alive between calls. This matters when:

• The tool has state - you're in a mysql shell, you've USEd a database, you're in a transaction. A bash tool can't hold that session open between calls.
• The tool has UI - htop, vim, k9s, lazygit. A bash tool gets garbage back because these apps paint full-screen interfaces with ANSI escape codes. tui-mcp renders them into a readable screenshot or text snapshot through xterm emulation.
• The interaction is multi-step - SSH prompts for a password, then a 2FA code, then you're in. An interactive installer asks questions. git rebase -i drops you into an editor. These are conversational flows that a stateless bash tool can't handle.
• You need to watch something - tail a log, monitor a build, wait for a deploy to finish. The session stays open, the agent can snapshot whenever it wants to check progress.
• The tool requires a TTY - some CLIs behave differently (or refuse to run) without a real terminal. node-pty gives them a real pty with xterm-256color, so everything works as expected.

A bash tool is exec(). tui-mcp is "sit down at a terminal and use it like a human." One runs commands, the other operates software.

Some example outputs of the screenshot tool:

Setup

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

Tools

Tool	Description
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

Interesting use cases

• remote ops: agent SSHs into a production box, tails logs, greps for errors, restarts a service, watches it come back up. it's reading the same terminal output a human SRE would see. no custom APIs needed.
• legacy system interaction: ncurses admin panels, mysql cli, redis-cli, psql - the agent can drive all of these. stuff that will never get a REST API.
• multi-session orchestration: agent launches 3-4 sessions simultaneously. one running a dev server, one running tests, one tailing logs, one in a debugger. it's basically pair programming with an extra set of hands.
• interactive debuggers: gdb, lldb, pdb, node --inspect. the agent can set breakpoints, step through code, inspect variables.
• infrastructure as conversation: kubectl, terraform, docker, aws cli. agent doesn't need the kubernetes MCP server or the AWS MCP server. it just uses the CLIs directly, same as a human would.

Most MCP servers wrap one specific tool or API. tui-mcp wraps the terminal itself, which is the universal interface that all tools already speak. It's MCP's eval().

Monitor

Watch and control all active sessions from your terminal:

npx tui-mcp monitor

Session list on the left, live ANSI-rendered terminal preview on the right. The monitor discovers every running tui-mcp server on the machine and aggregates their sessions.

Keys:

• j/k or arrows to move through servers and their sessions, g/G for top/bottom, mouse click and scroll also work
• enter on a session attaches - everything you type passes through to its pty, ctrl+\ detaches
• enter on a server opens the launch panel targeting it
• s fetches the session's full scrollback into a scrollable view, esc returns to live
• l launches a new session on the selected row's server (ctrl+s cycles the target)
• x twice within 3 seconds kills the selected session
• q quits

Attach, launch, kill, and scrollback need the server to be 1.2 or newer; sessions on older servers are marked ro (read-only) and can still be watched.

How it works

your app  <-->  node-pty  <-->  xterm-headless  <-->  MCP tools
                (pty)        (terminal emulator)    (screenshot, send_keys, etc.)

The app runs in a real pseudo-terminal via node-pty. Its output is parsed by xterm-headless (the same terminal emulator that powers VS Code's terminal, but without a DOM). The MCP tools read and interact with that parsed buffer.