Terminal MCP Server — Claude Code MCP server: terminals as UI
An MCP server that hands an AI agent live terminal sessions plus a structured screen snapshot, so it can press keys, click on found elements and wait for output.
claude mcp add --env DISPLAY=<DISPLAY> --env RUST_LOG=<RUST_LOG> --transport stdio terminal-mcp-server -- npx -y mcp-server-terminalWhat Terminal MCP Server does
Each session comes back as a state tree, and the agent works through tools. terminal_session_create opens it, terminal_snapshot captures the screen with detected UI elements, terminal_press_key sends arrows, F-keys or combos like Ctrl+X, terminal_click targets an element, terminal_wait_for blocks until text, an element or an idle state appears. Alongside sit terminal_type, terminal_read_output, session listing, closing and resizing.
A visible xterm window spawns by default. Pass --headless when there is no display to show. Visual mode on Linux and WSL needs X11, so DISPLAY goes into the MCP config. Native Windows gets headless only; the authors point Windows users to WSL for the full toolset.
Set RUST_LOG to error, warn, info, debug or trace for logging. Log lines go to stderr because stdout carries the MCP protocol. Miss DISPLAY in the config on Linux and the visual session simply will not start.
What it helps with
- drive an interactive program like htop and capture its screen
- send a down arrow and wait for the list to redraw
- run a shell command and read back its output
- click a menu entry the agent found on screen
- keep several terminal sessions open and close the extra ones
Example prompts for the agent
- Start a terminal session running htop and take a snapshot
- Press the down arrow and wait until the table updates
- Type
ls -la, hit Enter, then show me the output
How to install Terminal MCP Server
Platform CLI
claude mcp add --env DISPLAY=<DISPLAY> --env RUST_LOG=<RUST_LOG> --transport stdio terminal-mcp-server -- npx -y mcp-server-terminalReplace <…> with your own values
Platform CLI
codex mcp add terminal-mcp-server --env DISPLAY=<DISPLAY> --env RUST_LOG=<RUST_LOG> -- npx -y mcp-server-terminalReplace <…> with your own values
Config file
{
"mcpServers": {
"terminal-mcp-server": {
"command": "npx",
"args": [
"-y",
"mcp-server-terminal"
],
"env": {
"DISPLAY": "<DISPLAY>",
"RUST_LOG": "<RUST_LOG>"
}
}
}
}Replace <…> with your own values
Config file
{
"servers": {
"terminal-mcp-server": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"mcp-server-terminal"
],
"env": {
"DISPLAY": "<DISPLAY>",
"RUST_LOG": "<RUST_LOG>"
}
}
}
}Replace <…> with your own values
Platform CLI
gemini mcp add -e DISPLAY=<DISPLAY> -e RUST_LOG=<RUST_LOG> terminal-mcp-server npx -y mcp-server-terminalReplace <…> with your own values
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Terminal MCP Server
How do I install Terminal MCP Server in Claude Code?
Run claude mcp add mcp-server-terminal -- npx -y mcp-server-terminal. For DISPLAY and RUST_LOG, use the variant with --env DISPLAY=<DISPLAY> --env RUST_LOG=<RUST_LOG> --transport stdio.
What does Terminal MCP Server do?
It opens terminal sessions and lets the agent snapshot the screen with its UI elements, type text, send keystrokes, click and wait for a given state.
Does visual mode work on Windows?
Native Windows is headless only. The visible xterm window relies on X11, which on Windows means going through WSL.
