MCP Server Terminal

What aybelatchane/mcp-server-terminal MCP server does

The aybelatchane/mcp-server-terminal MCP server exposes interactive terminal control through the Model Context Protocol. Instead of treating a terminal only as a stream of text, it can provide a structured Terminal State Tree containing detected interface elements. This gives an agent a way to inspect and operate text-based user interfaces.

The server supports multiple concurrent terminal sessions. An agent can start a session with a specified command, list active sessions, read raw output, capture a structured snapshot, type text, send special keys, click detected elements by reference ID, wait for text or interface state, resize the terminal, and close the session.

How it works

Sessions spawn visible terminal windows by default. The server can also run headlessly with the --headless option, which is useful where a graphical display is unavailable. On Linux and WSL, visual operation uses X11 and requires an appropriate DISPLAY setting. Native Windows supports headless operation only; WSL is the documented choice for visual mode.

A typical interaction starts by creating a session for a CLI or TUI command. The agent can then take a snapshot, use detected element references for navigation, send keys such as arrows or Ctrl combinations, type input, and wait for text, an element, or an idle terminal. Raw output remains available when structured state is not needed.

Setup and configuration

Install the aybelatchane/mcp-server-terminal MCP server from npm with npx mcp-server-terminal, or download a release binary. The repository also documents building the Rust project from source, producing a terminal-mcp binary.

MCP client configuration uses npx with the mcp-server-terminal package. The README includes configurations for Claude Desktop, Cursor, Windsurf, and Cline, among other MCP-compatible clients. For direct execution, the package can be started with --headless as an argument.

No authentication or API credentials are described. RUST_LOG can be set to error, warn, info, debug, or trace; logs are written to stderr so stdout remains available for MCP communication. Visual Linux or WSL setups may need DISPLAY, such as :0.

Tools and capabilities

The aybelatchane/mcp-server-terminal MCP server provides these tools:

• Create, list, resize, and close terminal sessions.
• Read raw terminal output.
• Capture snapshots with detected UI elements.
• Type text and press special keys or key combinations.
• Click an element using its ref_id.
• Wait for text, an element, or an idle terminal.

Limitations and notes

Platform behavior differs by operating system. Linux and macOS support both architectures listed in the README and provide visual operation. Windows native is headless-only, while Windows through WSL supports visual mode with X11 and tmux. The README does not describe authentication, remote hosting, access controls, or persistent session storage. Use care when allowing an agent to control sessions that can execute commands, because the exposed terminal is the environment in which the started applications run.