What it does
terminal-mcp is a terminal emulator exposed over the Model Context Protocol. An AI assistant can type text, press keys, read the terminal buffer and capture screenshots, so it can watch a command-line or text-UI program run, or operate one on its own. It runs either alongside your own terminal, where the assistant joins a session you are using, or in a headless mode that bundles its own pseudo-terminal and needs no TTY, which suits CI pipelines, containers and remote environments. Several isolated sessions can run in one process, up to a configurable limit. Sessions can be recorded in the asciicast format for playback with asciinema, and an optional sandbox mode restricts filesystem and network access on macOS and Linux. A setup command writes the server entry into the MCP config of the tools it detects, including Codex CLI, GitHub Copilot CLI, Gemini CLI, OpenCode, Claude Code and Claude Desktop. Installation is through npm and needs Node.js 18 or later. The project is released under the MIT license.
Capabilities
- Nine tools for typing, key presses, reading the buffer, screenshots, recording and session management
- Screenshots as plain text, ANSI-coloured text or PNG
- Headless mode for CI, containers and remote environments
- Multiple isolated sessions in one process
- Recording to asciicast files that play back in asciinema
- Optional sandbox that limits filesystem and network access
When to use it
- Letting an assistant debug a command-line or text-UI program while you watch the same terminal
- Having an agent drive terminal-based tools without a person present, such as in CI
- Running a long build in one session while diagnostics run in another
- Recording a terminal session to replay later
