Log inSubmit server
Terminal Use logo

Terminal Use

Drives interactive shells and terminal programs through MCP with text, screenshots, keyboard, mouse, and session controls.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Terminal Use

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "terminal-use": {
      "command": "npx",
      "args": [
        "-y",
        "terminal-use"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

terminal-use MCP server gives AI agents access to interactive shell sessions through a real pseudo-terminal and terminal emulator. Agents can type commands, press keys, wait for output, read screen or scrollback text, and capture rendered terminal screenshots. It also supports mouse clicks, scrolling, resizing, batching inputs, and managing multiple sessions. Reach for terminal-use when a workflow involves programs such as vim, REPLs, pagers, interactive installers, SSH prompts, or terminal user interfaces rather than simple command execution.

Use cases

  • Run and inspect interactive CLI programs
  • Edit files in vim or another terminal editor
  • Drive installers and menu-based terminal applications
  • Test CLIs and terminal user interfaces
  • Observe and control an agent session manually

Key features

  • Interactive pseudo-terminal sessions
  • Text and PNG screen inspection
  • Keyboard, mouse, scrolling, and resize input
  • Wait conditions for commands and output
  • Batch input and session lifecycle controls
  • Optional Docker execution and human attachment

Tools13

What Terminal Use lets your agent do. Expand a tool for its parameters.

Self-reported~230 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 2d ago

Recent health check succeeded.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 14d ago via OSV.dev · terminal-use (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars1Stargazers on the source repository.
npm downloads531Package downloads in the last 30 days.
Last commit7d agoMost recent push to the default branch.
Tools exposed13Callable tools this server registers over MCP.
Directory activity1 viewsConfig copies, upvotes, and views on AllMCPs.

How Terminal Use works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Terminal Use

terminal-use is an MCP server that connects AI agents to real shell sessions through a pseudo-terminal and terminal emulator. Its tools create and manage sessions, type text, press keys, wait for output, read screen state, capture PNG screenshots, click, scroll, resize, batch inputs, and reset sessions.

Install it through an MCP client using the command `npx -y terminal-use`. Claude Code, Cursor, VS Code, Codex, Gemini CLI, and Claude Desktop configurations are shown, and the server requires Node.js 22.12 or newer on macOS, Linux, or Windows.

Yes, terminal-use works with Cursor through its MCP installation link or configuration. Add the server with the command `npx -y terminal-use`, then start a new client session and ask the agent to operate a terminal.

Yes, terminal-use includes a Dockerfile and can run with `docker build` and `docker run -i --rm`. The agent then receives shells inside the container, with host files available only through mounted directories, and local terminal attachment is unavailable in this setup.

Start sessions with login mode enabled using the `--login` server option or `login: true` in `terminal_create`. A login shell reads profile files such as `.zprofile`, `.bash_profile`, or `.profile`, which can set up tools such as Node, Homebrew, or pyenv.

Related MCP servers

All in Command Line All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewTerminal Use AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/terminal-use?style=directory)](https://allmcps.com/mcp/terminal-use)
HTML Embed
<a href="https://allmcps.com/mcp/terminal-use"><img src="https://allmcps.com/api/badge/terminal-use?style=directory" alt="Terminal Use on AllMCPs" /></a>