Skip to content
Back to search

terminal-mcp

A terminal emulator exposed via MCP for AI assistants

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/elleryfamilia--terminal-mcp/badge.svg)](/listings/elleryfamilia--terminal-mcp)

HTML

<a href="/listings/elleryfamilia--terminal-mcp"><img src="/api/listings/elleryfamilia--terminal-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

npm install -g @ellery/terminal-mcp

Or via install script:

curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash

Configure your AI tools

Wire `terminal-mcp` into the MCP config of every AI tool installed on your machine in one shot:

terminal-mcp setup                      # detect & install for all detected tools
terminal-mcp setup --dry-run            # preview without writing
terminal-mcp setup --client claude-code,gemini   # specific tools only
terminal-mcp setup --uninstall          # remove the entry from each tool

Supported clients (each gets the right schema for its config format):

| Client | Config file | Format | |---|---|---| | OpenAI Codex CLI | `~/.codex/config.toml` | TOML | | GitHub Copilot CLI | `~/.copilot/mcp-config.json` | JSON | | Gemini CLI | `~/.gemini/settings.json` | JSON | | OpenCode | `~/.config/opencode/opencode.json` | JSON | | Claude Code | `~/.claude.json` | JSON | | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) | JSON |

A `.bak` of any pre-existing config is written next to the original on first install. The `terminal-mcp` entry is added without disturbing other servers or unrelated keys; running `setup` again is a no-op.

Upgrading

npm install -g @ellery/terminal-mcp@latest

Interactive mode will print a banner on next launch when a newer release is available — `terminal-mcp` checks the npm registry once per day and caches the result. Headless and MCP-client modes never check or print anything (so MCP stdio stays clean). To opt out entirely, set `NO_UPDATE_NOTIFIER=1` or pass `--no-update-notifier`.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 512 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="logo.png" alt="Terminal MCP" width="600">
  3. </p>
  4. <p align="center">
  5. <strong>Let AI see and interact with your terminal.</strong>
  6. </p>
  7. <p align="center">
  8. Terminal MCP gives LLMs a shared view of your terminal session. Perfect for debugging CLIs and TUI applications in real-time, or letting AI drive terminal-based tools autonomously.
  9. </p>
  10. ## Install
  11. ```bash
  12. npm install -g @ellery/terminal-mcp
  13. ```
  14. Or via install script:
  15. ```bash
  16. curl -fsSL https://raw.githubusercontent.com/elleryfamilia/terminal-mcp/main/install.sh | bash
    • Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
    • Line 22 on GitHub
  17. ```
  18. ### Configure your AI tools
  19. Wire `terminal-mcp` into the MCP config of every AI tool installed on your machine in one shot:
  20. ```bash
  21. terminal-mcp setup # detect & install for all detected tools
  22. terminal-mcp setup --dry-run # preview without writing
  23. terminal-mcp setup --client claude-code,gemini # specific tools only
  24. terminal-mcp setup --uninstall # remove the entry from each tool
  25. ```
  26. Supported clients (each gets the right schema for its config format):
  27. | Client | Config file | Format |
  28. |---|---|---|
  29. | OpenAI Codex CLI | `~/.codex/config.toml` | TOML |
  30. | GitHub Copilot CLI | `~/.copilot/mcp-config.json` | JSON |
  31. | Gemini CLI | `~/.gemini/settings.json` | JSON |
  32. | OpenCode | `~/.config/opencode/opencode.json` | JSON |
  33. | Claude Code | `~/.claude.json` | JSON |
  34. | Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) / `%APPDATA%\Claude\claude_desktop_config.json` (Windows) | JSON |
  35. A `.bak` of any pre-existing config is written next to the original on first install. The `terminal-mcp` entry is added without disturbing other servers or unrelated keys; running `setup` again is a no-op.
  36. ### Upgrading
  37. ```bash
  38. npm install -g @ellery/terminal-mcp@latest
  39. ```
  40. Interactive mode will print a banner on next launch when a newer release is available — `terminal-mcp` checks the npm registry once per day and caches the result. Headless and MCP-client modes never check or print anything (so MCP stdio stays clean). To opt out entirely, set `NO_UPDATE_NOTIFIER=1` or pass `--no-update-notifier`.
  41. ## Features
  42. - **Full Terminal Emulation**: Uses xterm.js headless for accurate VT100/ANSI emulation
  43. - **Cross-Platform PTY**: Native pseudo-terminal support via node-pty (macOS, Linux, Windows)
  44. - **MCP Protocol**: Implements Model Context Protocol for AI assistant integration
  45. - **Session Recording**: Record terminal sessions to asciicast format for playback with asciinema
  46. - **Simple API**: Nine tools covering input, observation, recording, and session lifecycle
  47. - **Headless Mode**: Run as a standalone MCP server without a TTY — ideal for CI, containers, and non-interactive environments
  48. - **Multi-Session**: Run multiple isolated terminal sessions in one process, addressed by `sessionId`
  49. - **Sandbox Mode**: Optional security restrictions for filesystem and network access
  50. ## Building from Source
  51. ```bash
  52. npm install
  53. npm run build
  54. ```
  55. ## Usage
  56. ### MCP Configuration
  57. Add to your MCP client settings:
  58. ```json
  59. {
  60. "mcpServers": {
  61. "terminal": {
  62. "command": "terminal-mcp"
  63. }
  64. }
  65. }
  66. ```
  67. With custom options:
  68. ```json
  69. {
  70. "mcpServers": {
  71. "terminal": {
  72. "command": "terminal-mcp",
  73. "args": ["--cols", "100", "--rows", "30", "--shell", "/bin/zsh"]
  74. }
  75. }
  76. }
  77. ```
  78. ### Command-Line Options
  79. ```
  80. terminal-mcp [OPTIONS]
  81. Options:
  82. --cols <number> Terminal width in columns (default: 120)
  83. --rows <number> Terminal height in rows (default: 40)
  84. --shell <path> Shell to use (default: $SHELL or bash)
  85. --headless Run in headless mode (embedded PTY + MCP over stdio, no TTY needed)
  86. --sandbox Enable sandbox mode (restricts filesystem/network)
  87. --sandbox-config <path> Load sandbox config from JSON file
  88. --version, -v Show version number
  89. --help, -h Show help message
  90. Recording Options:
  91. --record [mode] Enable recording (default mode: always)
  92. Modes: always, on-failure, off
  93. --record-dir <dir> Recording output directory
  94. (default: ~/.local/state/terminal-mcp/recordings)
  95. --idle-time-limit <sec> Max idle time between events (default: 2s)
  96. --max-duration <sec> Max recording duration (default: 3600s)
  97. --inactivity-timeout <sec> Stop after no output (default: 600s)
  98. Multi-Session Options:
  99. --max-sessions <n> Max concurrent sessions (default: 5)
  100. --session-idle-timeout <sec> Idle non-default sessions are auto-destroyed
  101. after this period (default: 600s)
  102. ```
  103. ## Headless Mode
  104. By default, Terminal MCP uses a **dual-process architecture**: you run `terminal-mcp` in an interactive terminal (which creates a Unix socket), then your MCP client spawns a second instance that connects to that socket. This requires a TTY.
  105. **Headless mode** (`--headless`) eliminates this requirement by spawning an embedded PTY internally and serving MCP directly over stdio in a single process. No interactive terminal session, no socket — just a self-contained MCP server with a built-in terminal.
  106. ### When to use headless mode
  107. - **CI/CD pipelines** — no TTY available
  108. - **Docker containers** — no interactive shell to run alongside
  109. - **Remote/cloud environments** — MCP servers spawned by automation
  110. - **Simplified setup** — single process, no socket coordination needed
  111. ### Configuration
  112. ```json
  113. {
  114. "mcpServers": {
  115. "terminal": {
  116. "command": "terminal-mcp",
  117. "args": ["--headless", "--cols", "120", "--rows", "40"]
  118. }
  119. }
  120. }
  121. ```
  122. ### How it works
  123. ```
  124. MCP Client (Claude Code, etc.)
  125. │ STDIO (JSON-RPC)
  126. ▼
  127. terminal-mcp --headless
  128. ├── MCP Server (stdio transport)
  129. ├── Terminal Emulator (@xterm/headless)
  130. └── Embedded PTY (node-pty)
  131. │
  132. ▼
  133. Shell Process (bash, zsh, etc.)
  134. ```
  135. In headless mode, the terminal session is initialized eagerly at startup, so all tools (`type`, `sendKey`, `getContent`, `takeScreenshot`, `startRecording`, `stopRecording`, `createSession`, `listSessions`, `destroySession`) are available immediately.
  136. ## MCP Tools
  137. All input/output tools (`type`, `sendKey`, `getContent`, `takeScreenshot`) accept an optional `sessionId` argument. Omit it to target the default session; pass the ID returned by `createSession` to drive a specific session.
  138. ### `type`
  139. Send text input to the terminal.
  140. ```json
  141. {
  142. "name": "type",
  143. "arguments": {
  144. "text": "echo hello"
  145. }
  146. }
  147. ```
  148. ### `sendKey`
  149. Send special keys or key combinations.
  150. ```json
  151. {
  152. "name": "sendKey",
  153. "arguments": {
  154. "key": "Enter"
  155. }
  156. }
  157. ```
  158. Supported keys:
  159. - Basic: `Enter`, `Tab`, `Escape`, `Backspace`, `Delete`
  160. - Arrow: `ArrowUp`, `ArrowDown`, `ArrowLeft`, `ArrowRight`
  161. - Navigation: `Home`, `End`, `PageUp`, `PageDown`, `Insert`
  162. - Function: `F1` through `F12`
  163. - Control: `Ctrl+A` through `Ctrl+Z`, `Ctrl+C`, `Ctrl+D`, etc.
  164. ### `getContent`
  165. Get the terminal buffer as plain text.
  166. ```json
  167. {
  168. "name": "getContent",
  169. "arguments": {
  170. "visibleOnly": false
  171. }
  172. }
  173. ```
  174. ### `takeScreenshot`
  175. Capture the terminal state. Supports three output formats:
  176. | Format | Description |
  177. |--------|-------------|
  178. | `text` (default) | JSON with plain text content, cursor position, and dimensions |
  179. | `ansi` | JSON with ANSI color escape codes preserved in the content field |
  180. | `png` | Color screenshot as a PNG image (requires `@resvg/resvg-js`) |
  181. ```json
  182. {
  183. "name": "takeScreenshot",
  184. "arguments": { "format": "text" }
  185. }
  186. ```
  187. The `ansi` format reconstructs SGR escape sequences from the terminal's cell buffer, preserving 16-color, 256-color, and 24-bit truecolor attributes along with bold, dim, italic, and underline styles.
  188. The `png` format returns an MCP `image` content block with base64-encoded PNG data, rendered with the One Dark color theme and macOS-style window chrome.
  189. ### `startRecording`
  190. Start recording terminal output to an asciicast v2 file.
  191. ```json
  192. {
  193. "name": "startRecording",
  194. "arguments": {
  195. "mode": "always",
  196. "idleTimeLimit": 2,
  197. "maxDuration": 3600
  198. }
  199. }
  200. ```
  201. Options:
  202. - `mode`: `always` (save all) or `on-failure` (save only on non-zero exit)
  203. - `outputDir`: Custom output directory
  204. - `idleTimeLimit`: Max seconds between events (caps pauses in playback)
  205. - `maxDuration`: Auto-stop after N seconds
  206. - `inactivityTimeout`: Auto-stop after N seconds of no output
  207. ### `stopRecording`
  208. Stop a recording and finalize the asciicast file.
  209. ```json
  210. {
  211. "name": "stopRecording",
  212. "arguments": {
  213. "recordingId": "abc123"
  214. }
  215. }
  216. ```
  217. ### `createSession`
  218. Create a new terminal session and return its metadata. Use the returned `sessionId` to target this session in subsequent tool calls.
  219. ```json
  220. {
  221. "name": "createSession",
  222. "arguments": {
  223. "shell": "/bin/zsh",
  224. "cols": 100,
  225. "rows": 30
  226. }
  227. }
  228. ```
  229. All arguments are optional. Returns:
  230. ```json
  231. {
  232. "sessionId": "3029d",
  233. "shell": "/bin/zsh",
  234. "cols": 100,
  235. "rows": 30,
  236. "createdAt": "2026-04-25T12:58:01.072Z",
  237. "lastActivityAt": "2026-04-25T12:58:01.072Z",
  238. "isDefault": false
  239. }
  240. ```
  241. ### `listSessions`
  242. List all active sessions including the default. Reports configured limits.
  243. ```json
  244. { "name": "listSessions", "arguments": {} }
  245. ```
  246. ### `destroySession`
  247. Destroy a session by ID. The default session cannot be destroyed.
  248. ```json
  249. {
  250. "name": "destroySession",
  251. "arguments": { "sessionId": "3029d" }
  252. }
  253. ```
  254. ## Multi-Session
  255. By default, every tool call without a `sessionId` targets a single auto-created **default session** — the same behavior the project has always had. Pass `sessionId` to drive multiple isolated PTYs from one process.
  256. - The default session is created on first use and cannot be destroyed.
  257. - Additional sessions are created by `createSession` and tracked until they're destroyed or idle-evicted (`--session-idle-timeout`, default 600s).
  258. - Concurrent sessions are capped at `--max-sessions` (default 5).
  259. - An active recording captures output from all sessions in the process.
  260. Typical use case: an AI agent driving a long-running build in one session while running diagnostics in another, without command interleaving.
  261. ## Sandbox Mode
  262. Run the terminal with restricted filesystem and network access:
  263. ```bash
  264. # Interactive permission configuration
  265. terminal-mcp --sandbox
  266. # With a config file
  267. terminal-mcp --sandbox --sandbox-config ~/.terminal-mcp-sandbox.json
  268. ```
  269. The interactive mode shows a TUI dialog to configure permissions:
  270. <p align="center">
  271. <img src="sandbox-permissions.png" alt="Sandbox Permissions Dialog" width="400">
  272. </p>
  273. - **Read/Write**: Full access (current directory, /tmp, caches)
  274. - **Read-Only**: Can read but not modify (home directory)
  275. - **Blocked**: No access (SSH keys, cloud credentials, auth tokens)
  276. Example config file:
  277. ```json
  278. {
  279. "filesystem": {
  280. "readWrite": [".", "/tmp", "~/.cache"],
  281. "readOnly": ["~"],
  282. "blocked": ["~/.ssh", "~/.aws", "~/.gnupg"]
  283. },
  284. "network": {
  285. "mode": "all"
  286. }
  287. }
  288. ```
  289. Platform support:
  290. - **macOS**: Full support via sandbox-exec (Seatbelt)
  291. - **Linux**: Full support via bubblewrap (requires `bwrap` installed)
  292. - **Windows**: Graceful fallback (runs without sandbox)
  293. See [Sandbox Documentation](./docs/sandbox.md) for detailed configuration options.
  294. ## Recording
  295. Terminal MCP can record sessions to [asciicast v2](https://docs.asciinema.org/manual/asciicast/v2/) format, compatible with [asciinema](https://asciinema.org/) for playback.
  296. ### Quick Start
  297. ```bash
  298. # Start with recording enabled
  299. terminal-mcp --record
  300. # Run your commands, then exit
  301. exit
  302. # Output shows the saved file path:
  303. # Recordings saved:
  304. # ~/.local/state/terminal-mcp/recordings/20240115_143022.cast
  305. #
  306. # Play with: asciinema play <file>
  307. ```
  308. ### Playback
  309. Install asciinema to play back recordings:
  310. ```bash
  311. # macOS
  312. brew install asciinema
  313. # Linux/pip
  314. pip install asciinema
  315. # Play a recording
  316. asciinema play ~/.local/state/terminal-mcp/recordings/20240115_143022.cast
  317. # Play at 2x speed
  318. asciinema play -s 2 recording.cast
  319. ```
  320. ### Recording Modes
  321. - **`always`** (default): Save every recording
  322. - **`on-failure`**: Only save if the session exits with a non-zero code (useful for debugging failed CI runs)
  323. ```bash
  324. # Only save recordings when something fails
  325. terminal-mcp --record=on-failure
  326. ```
  327. ### MCP Tool Recording
  328. AI assistants can also control recording programmatically via MCP tools:
  329. 1. Call `startRecording` to begin capturing
  330. 2. Perform terminal operations
  331. 3. Call `stopRecording` to finalize and save
  332. This enables AI-driven workflows like "record this debugging session" or "capture this demo".
  333. ## Architecture
  334. Terminal MCP has three operating modes:
  335. | Mode | Flag | Stdin | Description |
  336. |------|------|-------|-------------|
  337. | **Interactive** | *(default)* | TTY | User gets a shell; AI connects via Unix socket |
  338. | **Client** | *(default)* | non-TTY | Connects to an interactive session's socket, serves MCP over stdio |
  339. | **Headless** | `--headless` | any | Self-contained: embedded PTY + MCP server over stdio |
  340. ### Headless mode (recommended for MCP configs)
  341. ```
  342. MCP Client (Claude Code, etc.)
  343. │ STDIO (JSON-RPC)
  344. ▼
  345. terminal-mcp --headless
  346. ├── MCP SDK (@modelcontextprotocol/sdk)
  347. ├── Terminal Emulator (@xterm/headless)
  348. └── Embedded PTY (node-pty)
  349. │
  350. ▼
  351. Shell Process (bash, zsh, etc.)
  352. ```
  353. ### Interactive + Client mode (two-process)
  354. ```
  355. terminal-mcp (interactive, in your terminal)
  356. ├── User shell (stdin/stdout)
  357. └── Unix socket server (/tmp/terminal-mcp.sock)
  358. ▲
  359. │ JSON-RPC over socket
  360. ▼
  361. terminal-mcp (client, spawned by MCP client)
  362. └── MCP server (stdio transport)
  363. ```
  364. ## Example Session
  365. ```bash
  366. # Type a command
  367. {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"type","arguments":{"text":"ls -la"}}}
  368. # Send Enter key
  369. {"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"sendKey","arguments":{"key":"Enter"}}}
  370. # Get the output
  371. {"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"getContent","arguments":{}}}
  372. ```
  373. ## Development
  374. ```bash
  375. npm run build # Compile TypeScript
  376. npm run dev # Run with tsx (development)
  377. ```
  378. ## Documentation
  379. See the [docs](./docs/) folder for detailed documentation:
  380. - [Overview](./docs/index.md)
  381. - [Installation](./docs/installation.md)
  382. - [Tools Reference](./docs/tools.md)
  383. - [Recording](./docs/recording.md)
  384. - [Configuration](./docs/configuration.md)
  385. - [Sandbox Mode](./docs/sandbox.md)
  386. - [Examples](./docs/examples.md)
  387. - [Architecture](./docs/architecture.md)
  388. ## Requirements
  389. - Node.js 18.0.0 or later
  390. - Windows 10 version 1809 or later (for ConPTY support)
  391. ## License
  392. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.