terminal-use MCP server

terminal-use

An MCP server that lets an AI agent use a real terminal the way a person does: type, press keys, click, read the screen, take a screenshot.

Every frame above was drawn by terminal-use's own screenshot renderer; the caption on each is the tool call that produced it.

Most agent shell tools run a command and hand back its output. That breaks down for anything interactive — vim, htop, a REPL, an installer asking questions, git rebase -i, an SSH session. terminal-use gives the agent a shell on a real pseudo-terminal, rendered by a real terminal emulator, so full-screen and interactive programs work and the agent sees what you would see.

• Real PTY, real emulator — colors, cursor movement and the alternate screen are interpreted, not passed along as escape codes.
• Text and pixels — read the screen as plain text, or as a PNG when layout and color matter.
• Waits properly — block until a command actually finishes, or until some text appears.
• Watch along — attach your own terminal to any session and type alongside the agent.

Quick start

Requires Node.js 20.19 or newer, on macOS, Linux or Windows.

Claude Code

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

Other MCP clients (Claude Desktop, Cursor, and anything else that takes a command):

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

Start a new session in your client and ask it to do something in a terminal, for example: "Open vim, write a haiku into /tmp/haiku.txt, save and quit, then show me a screenshot of cat-ing it."

Server options go after the command: npx -y terminal-use --cols 100 --rows 40.

"command not found" inside a session

If programs that work in your own terminal (node, brew, pyenv…) are missing inside a session, the server probably inherited a bare environment. That happens when the MCP client is started from the Dock or a launcher instead of a terminal: your PATH is set up by your shell's profile files (~/.zprofile, ~/.bash_profile, ~/.profile), and nothing has read them.

A login shell reads those files. Turn it on for every session with the --login server flag, or for one session with login: true on terminal_create. It is off by default because it makes each shell slower to start and runs whatever your profile runs. It has no effect in PowerShell or cmd.exe, which have no login mode.

Tools

Every tool except terminalcreate and terminallist takes the sessionId that terminal_create returns.

Shortened. The full README is on GitHub.