Skip to content
MCP server

terminal-use

Lets AI agents drive a real terminal with typing, key presses, clicks and screenshots

Runs locallyStatus and history
Install
Pricing
Open source
Platforms
CLI, macOS, Linux
Runs
Locally
Version
0.2.1
Listing updated
1 day ago

About terminal-use

terminal-use is an open-source MCP server for developer tools. It runs locally on your machine and is started by your AI client.

Most agent shell tools run a command and return its output, which fails for anything interactive. This server instead runs sessions on a real pseudo-terminal with a terminal emulator, so programs like vim, htop, REPLs, installers and SSH prompts behave as they do for a person. The agent can read the screen as text or render it as a PNG.

Sessions can be an interactive shell or a single command, in which case the exit status is reported and the final screen stays readable. That makes it suitable for testing a CLI or TUI. Waiting is built in, so the agent can block until a command finishes, a regex appears or output goes quiet. You can also attach your own terminal to a session and type alongside the agent, similar to a shared tmux session.

It needs Node.js 22.12 or newer and runs on macOS, Linux or Windows. A Dockerfile is provided for boxing the agent in, and an optional Agent Skill gives recipes for vim, pagers, REPLs and ssh prompts.

Install

Run in a terminal

claude mcp add terminal-use -- npx -y terminal-use

Add to claude_desktop_config.json

{
  "mcpServers": {
    "terminal-use": {
      "command": "npx",
      "args": [
        "-y",
        "terminal-use"
      ]
    }
  }
}
Install in CursorOpens Cursor, which asks you to confirm. Or add it by hand:

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "terminal-use": {
      "command": "npx",
      "args": [
        "-y",
        "terminal-use"
      ]
    }
  }
}
Install in VS CodeOpens VS Code, which asks you to confirm. Or add it by hand:

Add to .vscode/mcp.json

{
  "servers": {
    "terminal-use": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "terminal-use"
      ]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json

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

Add to your client's MCP settings (most use this shape)

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

Tools this server provides (13)

Taken from the project documentation; the running server may differ.

terminal_create
Starts a session as an interactive shell or running one program.
terminal_list
Lists sessions.
terminal_destroy
Ends a session.
terminal_type
Types text, with optional paste.
terminal_press
Presses a key or combination.
terminal_wait
Waits for a command to finish, a regex or quiet output.
terminal_read
Reads the screen or scrollback as text.
terminal_screenshot
Renders the screen as a PNG.
terminal_click
Left-clicks a cell with a preview step.
terminal_scroll
Turns the mouse wheel over a cell.
terminal_batch
Sends several inputs in one call.
terminal_resize
Changes the terminal size.
terminal_reset
Clears the screen or restarts the shell.

What it does

Real PTY and emulator
Interprets colours, cursor movement and the alternate screen.
Text and screenshots
Read the screen as plain text or as a PNG.
Smart waiting
Wait for command exit, matching text or quiet output.
Watch along
Attach your own terminal to a session and type with the agent.
Docker isolation
Run in a container so the agent sees only mounted files.
Bundled skill
An optional Agent Skill with recipes for common interactive programs.

Good for

  • Let an agent edit a file in vim
  • Test a CLI or TUI end to end
  • Drive an installer that asks questions
  • Walk through an interactive git rebase

Pricing

Open source

Open-source npm package; no pricing listed.

terminal-use FAQ

What are the requirements?

Node.js 22.12 or newer, on macOS, Linux or Windows.

How do I add it to Claude Code?

Run claude mcp add terminal-use --scope user -- npx -y terminal-use.

Why does it say command not found?

The server may have inherited a bare environment; enable the login shell with the --login flag or login: true.

Can I contain what the agent can reach?

Yes, the Docker setup limits it to what you mount.

Is terminal-use free?

Yes. terminal-use is open source, so you can use and self-host it for free.

How do I add terminal-use to Claude Code?

Run this command in your terminal: claude mcp add terminal-use -- npx -y terminal-use

What are the best alternatives to terminal-use?

The closest alternatives to terminal-use are REA, Codebase Memory, GitHub, Serena MCP: the IDE for your agent and XERJ.

Alternatives to terminal-use

  1. REA

    MCP server

    CLI and MCP server that lets coding agents reverse engineer apps and binaries

    Runs locally
    • Open source
    • 464K GitHub stars
    • Developer tools
  2. Codebase Memory

    MCP server

    Local MCP server that builds a code knowledge graph for AI coding agents

    Runs locally
    • Open source
    • 48.7K GitHub stars
    • Knowledge and memory
  3. GitHub

    MCP server

    Official MCP server connecting AI assistants to GitHub repos, issues and workflows

    Not checked yet
    • Remote
    • Open source
    • 34.5K GitHub stars
    • Developer tools
  4. MCP toolkit giving coding agents symbol-level code retrieval and editing

    Runs locally
    • Open source
    • 31.5K GitHub stars
    • Developer tools
  5. XERJ

    MCP server

    Local search engine for AI agents with cited answers over your code and docs

    Runs locally
    • Open source
    • 19.2K GitHub stars
    • Knowledge and memory
  6. Ouroboros

    MCP server

    Spec-first layer that pins requirements and verifies results of AI coding agent work

    Runs locally
    • Open source
    • 6.4K GitHub stars
    • Developer tools