Terminal

Terminal MCP is an MCP server that gives AI assistants a real-time view of your terminal session. It emulates a terminal environment so language models can see command output, type input, and interact with CLI or TUI applications.

You can use it to debug command-line tools with AI assistance or let autonomous agents drive terminal-based workflows. The MCP server communicates over STDIO using JSON-RPC per the Model Context Protocol specification.

Features

• Full Terminal Emulation: Uses xterm.js headless to ensure accurate VT100/ANSI emulation, meaning the AI sees exactly what a human sees.
• Cross-Platform PTY: Leverages node-pty to provide native pseudo-terminal support across macOS, Linux, and Windows.
• Session Recording: Captures terminal sessions in asciicast v2 format, which users can play back using asciinema.
• Sandbox Security: Offers a configurable sandbox mode to restrict filesystem and network access for safer AI execution.
• Comprehensive Toolset: Provides six distinct tools for typing, key transmission, screen reading, and session management.
• Configurable Environment: Supports customization of terminal dimensions (rows/cols) and shell selection (zsh, bash, etc.).

Use Cases

• Autonomous CLI Debugging: An AI agent can run a failing build command, read the error output from the buffer, apply a fix, and rerun the command to verify the solution without human intervention.
• TUI Application Interaction: Developers can use this server to let AI agents navigate interactive interfaces like vim, htop, or configuration wizards by sending specific key combinations (e.g., Arrow keys, Escape, Enter).
• Auditable AI Operations: Security teams can enable the “record on failure” mode to automatically generate playback files of AI sessions that result in errors, facilitating post-mortem analysis of agent behavior.
• Safe Experimentation: Users can grant an AI agent access to a terminal restricted by the Sandbox mode, ensuring the agent cannot modify critical system files or access sensitive SSH keys while performing tasks.

How to Use It

1. Install the MCP server

Option 1: NPM Global Install

npm install -g @ellery/terminal-mcp

Option 2: Install Script

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

2. Add the MCP server to your MCP client configuration file (typically claude_desktop_config.json or similar).

Basic Configuration

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp"
    }
  }
}

Advanced Configuration (Custom Shell & Dimensions)

You can pass arguments to customize the terminal environment.

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp",
      "args": ["--cols", "100", "--rows", "30", "--shell", "/bin/zsh"]
    }
  }
}

3. The terminal-mcp executable accepts the following flags to control behavior:

• --cols <number>: Sets terminal width in columns (Default: 120).
• --rows <number>: Sets terminal height in rows (Default: 40).
• --shell <path>: Specifies the shell to launch (Default: $SHELL or bash).
• --sandbox: Enables sandbox mode with interactive permissions dialog.
• --sandbox-config <path>: Loads sandbox permissions from a specific JSON file.
• --record [mode]: Enables recording. Modes: always (default), on-failure, off.
• --record-dir <dir>: Sets the directory for saving recordings (Default: ~/.local/state/terminal-mcp/recordings).
• --idle-time-limit <sec>: Sets max idle time between events in recordings (Default: 2s).
• --max-duration <sec>: Sets max recording duration (Default: 3600s).
• --inactivity-timeout <sec>: Stops recording after N seconds of no output (Default: 600s).

4. Available MCP Tools

type: Sends text input to the terminal. This acts as the primary method for entering commands.

• Argument: text (string) – The command or text to type.

{
  "name": "type",
  "arguments": { "text": "echo hello" }
}

sendKey: Sends non-text keys or key combinations. This is essential for TUI navigation and process control.

• Argument: key (string) – The key identifier.
• Supported Keys:
  • Basic: Enter, Tab, Escape, Backspace, Delete
  • Arrows: ArrowUp, ArrowDown, ArrowLeft, ArrowRight
  • Navigation: Home, End, PageUp, PageDown, Insert
  • Function: F1 – F12
  • Control: Ctrl+A – Ctrl+Z, Ctrl+C, Ctrl+D

getContent: Retrieves the current terminal buffer as plain text. The AI uses this to “read” the screen.

• Argument: visibleOnly (boolean) – If true, returns only the visible viewport.

takeScreenshot: Captures the terminal state, including cursor position and dimensions.

startRecording” Programmatically starts recording the session to an asciicast v2 file.

• Arguments:
  • mode: always or on-failure.
  • outputDir: Custom path for the file.
  • idleTimeLimit: Cap on pause duration during playback.
  • maxDuration: Auto-stop limit in seconds.

stopRecording” Finalizes the current recording and saves the file.

• Argument: recordingId (string) – The ID returned by startRecording.

5. Sandbox mode restricts what the terminal process can access. You can configure this interactively or via a JSON file.

Platform Requirements:

• macOS: Uses sandbox-exec (Seatbelt).
• Linux: Requires bwrap (Bubblewrap) to be installed.
• Windows: Falls back to running without sandbox (graceful degradation).

JSON Configuration Example:

Create a file (e.g., ~/.terminal-mcp-sandbox.json) to define permissions:

{
  "filesystem": {
    "readWrite": [".", "/tmp", "~/.cache"],
    "readOnly": ["~"],
    "blocked": ["~/.ssh", "~/.aws", "~/.gnupg"]
  },
  "network": {
    "mode": "all"
  }
}

Load this configuration using the --sandbox-config flag.

6. Terminal MCP records sessions in a format compatible with asciinema.

Recording Modes:

• always: Saves every session.
• on-failure: Saves only if the session exits with a non-zero code (ideal for CI/CD).

Playback:

You need asciinema to view the recordings.

# Install asciinema
brew install asciinema   # macOS
pip install asciinema    # Linux/pip
# Play a specific recording
asciinema play ~/.local/state/terminal-mcp/recordings/20240115_143022.cast

FAQs

Q: Does the sandbox mode work on Windows?
A: No. On Windows, the sandbox mode degrades gracefully, meaning the server runs without the sandbox restrictions.

Q: How does the AI know if a command failed?
A: The AI must inspect the terminal output using the getContent tool. Unlike a direct shell execution tool that might return an exit code immediately, Terminal MCP emulates a visual terminal. The AI reads the buffer to see error messages or exit codes echoed to the screen.

Q: Can I use this to run interactive programs like Vim?
A: Yes. The sendKey tool allows the AI to send control characters (like Escape, Ctrl+C, or arrow keys), which enables navigation and control within TUI applications like Vim or Nano.

Q: Where are recordings stored by default?
A: Recordings are saved to ~/.local/state/terminal-mcp/recordings unless you specify a different directory using the --record-dir flag.

Q: What happens if I don’t specify a shell?
A: The server defaults to the $SHELL environment variable. If that is not set, it falls back to bash.