# terminal-use [Health: Active]

**Category:** 🖥️ Command Line  
**Repository:** https://github.com/computer-agent-labs/terminal-use  
**GitHub Stars:** 1  
**npm Downloads (last month):** 531  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/terminal-use

## Description
Lets AI agents drive a real terminal: type, press keys, click, read the screen, take screenshots.

## Tools
Capabilities this server exposes over MCP:

- **terminal_create** — Start a session: an interactive shell, or one program with `command`. Optional `label`, `cols`, `rows`, `shell`, `cwd`, `env`, `login`, `scrollback`, `theme`.
- **terminal_list** — List sessions.
- **terminal_destroy** — End a session.
- **terminal_type** — Type text. `\n` presses Enter. `paste: true` sends it as one paste.
- **terminal_press** — Press a key or combination: `Enter`, `Ctrl+C`, `ArrowUp`, `Shift+Tab`, `Alt+Enter`, `F5`…
- **terminal_wait** — Wait for the running command to finish, for a regex to appear, or for output to go quiet.
- **terminal_read** — Read the screen or scrollback as text.
- **terminal_screenshot** — Render the screen as a PNG.
- **terminal_click** — Left-click a cell, with a preview step.
- **terminal_scroll** — Turn the mouse wheel over a cell.
- **terminal_batch** — Send several inputs in one call and get the screen back once.
- **terminal_resize** — Change the terminal size.
- **terminal_reset** — Clear the screen and scrollback, or restart the shell with `hardReset: true`.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "terminal-use": {
    "command": "npx",
    "args": ["-y","terminal-use"]
  }
}
```

## Documentation

## What terminal-use does

terminal-use exposes interactive terminal sessions over MCP. Instead of executing a command and returning only its output, it maintains a shell or program inside a pseudo-terminal. The terminal emulator interprets cursor movement, colors, alternate-screen behavior, and other terminal output so agents can work with applications as they appear in a terminal.

A session can start as an interactive shell or launch one specified program. Agents can enter text, send individual keys or key combinations, wait for completion or matching output, inspect the current screen or retained scrollback, and request a PNG rendering when visual layout matters. Human users can also attach to a session and type alongside the agent.

## How it works

MCP calls reach a Node.js process, which uses `node-pty` to run the configured shell and feeds its output into a headless xterm.js emulator. The server exposes the emulator state as text through `terminal_read` and as an image through `terminal_screenshot`.

Most tools use the `sessionId` returned by `terminal_create`. A session may run the default shell or a command passed at creation time. Command sessions route through the shell, so shell-specific quoting, pipes, and redirection apply. When the program exits, its status is reported and the final screen remains available for reading or screenshot capture. Input tools then return an error instead of restarting the finished process; `terminal_reset` with `hardReset: true` starts it again.

## Setup and configuration

Node.js 22.12 or newer is required. The server runs on macOS, Linux, and Windows. A typical stdio configuration starts it with `npx -y terminal-use`; server options can follow the command.

Useful options include `--shell`, `--cwd`, `--cols`, `--rows`, `--scrollback`, and `--login`. New sessions use the configured shell, working directory, terminal dimensions, and scrollback limit unless overridden in `terminal_create`. Login mode is disabled by default. Enabling it can load shell profile files and make commands such as `node`, `brew`, or `pyenv` available when the MCP client was launched outside a shell, but it can also slow startup and execute profile commands. Login mode does not affect PowerShell or `cmd.exe`.

A Dockerfile is included for running the server in a container. Mounting a directory at `/workspace` gives the containerized terminal access to that directory; the agent's shells then run inside the container rather than directly on the host. Sessions in this setup cannot be attached from the user's own terminal.

The optional Agent Skill provides usage guidance and recipes for terminal applications. Hosts that support MCP Skills can load it from the server, while Claude Code can install the skill files into its skills directory.

## Tools and capabilities

- `terminal_create` starts a shell or a specified program and accepts session settings such as `cwd`, environment values, dimensions, theme, login mode, and scrollback.
- `terminal_list` reports active sessions, including the exit status of completed command sessions.
- `terminal_destroy` ends a session.
- `terminal_type` enters text, with newline handling and an option to send the text as one paste.
- `terminal_press` sends keys and combinations such as Enter, Ctrl+C, function keys, and arrow keys.
- `terminal_wait` waits for process completion, a regular-expression match, or quiet output.
- `terminal_read` returns screen content or scrollback as text.
- `terminal_screenshot` renders the current terminal as a PNG.
- `terminal_click` clicks a screen cell after a preview step, while `terminal_scroll` sends mouse-wheel input over a cell.
- `terminal_batch` groups several inputs and returns the screen once.
- `terminal_resize` changes terminal dimensions.
- `terminal_reset` clears state or restarts a command with `hardReset: true`.

## Limitations and notes

The server starts with a default terminal size of 120 columns by 30 rows and retains 5,000 scrollback lines unless configured otherwise. Attach commands can let a person observe or control an active session; attached users share the shell identity of the server process. Session sockets are restricted to the owning user, but anyone who can connect to one receives a shell as that user. Each MCP client runs its own terminal-use process and session numbering starts from 1 for each process.

_Full upstream README: https://allmcps.com/mcp/terminal-use/readme_