tui-mcp

Purpose

tui-mcp is an MCP (Model Context Protocol) server whose goal is to expose the terminal itself as a general-purpose interface to AI assistants. Just as Chrome DevTools MCP is to the browser, tui-mcp is to the terminal: it lets AI start, screenshot, and interact with any TUI application.

It launches a real pseudo-terminal hosting a terminal application via node-pty, and the application thinks it is running in a real terminal. The output is parsed by xterm-headless (the terminal emulator behind the VS Code terminal, the DOM-free version), and the MCP tools read and manipulate that parsed buffer.

Main capabilities

• Launch any terminal application in a hosted pty.
• Take screenshots of and read text from the terminal interface.
• Send key input to the terminal.
• Maintain persistent, interactive sessions: the pty survives across multiple calls, supporting stateful tools (such as the mysql shell, transactions), full-screen UIs (htop, vim, k9s, lazygit), multi-step interactions (SSH passwords, 2FA, interactive installers, git rebase -i), continuous monitoring (tailing logs, builds, deployments), and CLIs that require a real TTY.
• Provide a real pty with xterm-256color generated by node-pty, so that CLIs requiring a TTY work normally.
• Support any TUI framework or no framework at all: vim, htop, bubbletea, textual, ink, inquirer, trend, ncurses, etc.
• All active sessions can be viewed and controlled from the terminal monitoring interface.

Difference from the bash tool

The bash tool runs discrete commands, fire-and-forget with each call, returning output after the process exits. tui-mcp maintains persistent, interactive sessions, with the pty staying alive between calls. This is especially important in the following scenarios:

• The tool is stateful: in the mysql shell a database has already been USE'd and it is in a transaction; the bash tool cannot maintain the session between calls.
• The tool has a UI: full-screen interfaces such as htop, vim, k9s, lazygit use ANSI escape codes, and the bash tool returns garbled text; tui-mcp renders them into readable screenshots or text snapshots through xterm emulation.
• The interaction is multi-step: SSH sequentiallyPrompt for passwords, 2FA verification codes; interactive installers ask questions; git rebase -i enters an editor. These conversational flows cannot be handled by a stateless bash tool.
• Need to monitor: tail logs, monitor builds, wait for deployments to complete. The session stays open, and the agent can take snapshots at any time to check progress.
• Tools require a TTY: some CLIs behave differently or refuse to run without a real terminal. node-pty provides a real pty with xterm-256color, so everything works as expected.

The bash tool is exec(), while tui-mcp is "sitting down at the terminal and using it like a human." One runs commands, the other operates software.

Usage

Launch any terminal application in a hosted pty, then screenshot it, read text, and send keystrokes. Multiple sessions can be launched at the same time (for example, one running a dev server, one running tests, one tailing logs, and one in a debugger), enabling multi-session orchestration.

All active sessions can be viewed and controlled from the terminal monitoring interface: the left side is the session list, and the right side is a terminal preview rendered with live ANSI. The monitoring interface discovers all tui-mcp servers running on the machine and aggregates their sessions.

Monitoring interface operations:

• Use j/k or the arrow keys to move between servers and sessions, g/G to go to the top/bottom, and mouse clicks and scrolling also work.
• Press enter on a session to attach: everything you type is sent to its pty, and ctrl+\ detaches.
• Press enter on a server to open the launch panel for it.
• s captures the session's full scrollback buffer into a scrollable view, and esc returns to live.
• l launches a new session on the server in the selected row (ctrl+s cycles the target).
• Press x twice within 3 seconds to terminate the selected session.

Attaching, launching, terminating, and scrollback require server version 1.2 or newer; sessions on older servers are marked ro (read-only) and can still be watched.

Use cases

• Remote operations: the agent logs in to a production machine over SSH, tails logs, greps errors, restarts services, and observes recovery. It reads the same terminal output as a human SRE, with no need for a custom API.
• Legacy system interaction: ncurses admin panels, mysql cli, redis-cli, psql, and other systems that will never get a REST API.
• Multi-session orchestration: launch 3-4 sessions at the same time, such as a dev server, tests, logs, and a debugger, equivalent to an extra pair of handsfor pair programming.
• Interactive debuggers: gdb, lldb, pdb, node --inspect, where the agent can set breakpoints, step through execution, and inspect variables.
• Infrastructure as conversation: kubectl, terraform, docker, aws cli. The agent does not need a Kubernetes MCP server or an AWS MCP server, and directly uses the CLI like a human.

Most MCP servers wrap a specific tool or API. tui-mcp wraps the terminal itself, the universal interface that all tools already use. It is the eval() of MCP.

Limitations

• Attaching, launching, terminating, and scrollback require server version 1.2 or newer; sessions on older servers are read-only.
• Details such as installation methods, specific charges or pricing, and platform support are not provided for now.