Terminal MCP Server

How to use

Ask your AI agent to manage terminal sessions, create interactive shells, or perform scripted actions. Typical tasks include starting a session with a command, typing input, sending keystrokes, resizing the terminal, taking snapshots of the UI, and reading terminal output. The server exposes a set of tools that your agent can invoke to control terminal behavior and respond to UI elements.

Common usage patterns include starting a session with a specific command, interacting with the session by typing commands, and capturing terminal state for visualization or decision making. You can also run the session in headless mode for environments without a visible display, which is useful for automated workflows and remote execution.

How to install

Prerequisites: ensure you have Node.js installed on your system. You can verify by running node -v and npm -v in your terminal.

Install the MCP server by running the runtime command: npx mcp-server-terminal.

(Optional) Build from source if you prefer building from the repo and running the binary instead of the npm package. Use your preferred language toolchain as shown in the instructions for the source project.

Configuration and usage notes

Connect your MCP client by configuring it to point at this server using the standard MCP connection method. The server is started locally by the command shown above, and you can pass additional flags as needed to tailor behavior.

Visual mode is enabled by default and opens a visible terminal window. To run headless for environments without a display, start the server with the --headless flag.

Visual mode and display options

By default, sessions spawn a visible terminal window. To run without a UI, use headless mode.

npx mcp-server-terminal --headless

X11 setup for Linux/WSL

If you need visual output in a Linux environment, ensure X11 is available and the DISPLAY variable is set in your MCP client configuration.

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["mcp-server-terminal"],
      "env": {
        "DISPLAY": ":0"
      }
    }
  }
}

Logging

Control logging verbosity by setting the RUST_LOG environment variable when starting the server. Levels include error, warn, info, debug, and trace.

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["mcp-server-terminal"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Platform support

The server supports Linux, macOS, and Windows (via WSL for full visual mode). See the platform table for details on architecture and capabilities.

Tools and capabilities

The server provides a comprehensive set of terminal-related actions that you can command from your MCP client, including creating sessions, listing sessions, resizing, typing input, pressing keys, clicking UI elements, waiting for text or UI state, and reading terminal output.

terminal_session_create

Start a new terminal session with a specified command or shell.

terminal_session_list

List all active terminal sessions managed by the MCP server.

terminal_session_close

Close a running terminal session by its identifier.

terminal_session_resize

Resize the terminal viewport to new width and height.

terminal_snapshot

Capture the current terminal state including visible UI elements.

terminal_type

Type text into the active terminal session.

terminal_press_key

Simulate pressing a key or key sequence (arrows, F-keys, Ctrl combos).

terminal_click

Interact with detected UI elements by clicking them.

terminal_wait_for

Wait for specific text, element, or idle state before continuing.

terminal_read_output

Read the raw terminal output for processing.