# aybelatchane/mcp-server-terminal [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/aybelatchane/mcp-server-terminal  
**GitHub Stars:** 19  
**npm Downloads (last month):** 356  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/aybelatchane-mcp-server-terminal

## Description
Playwright for terminals - interact with TUI/CLI applications through structured Terminal State Tree representation with element detection.

## Tools
Capabilities this server exposes over MCP:

- **terminal_type** — Type text into a terminal session
- **terminal_session_list** — List all active terminal sessions
- **terminal_session_create** — Create a new terminal session with the specified command
- **terminal_read_output** — Read raw output from a terminal session
- **terminal_session_close** — Close and terminate a terminal session
- **terminal_snapshot** — Capture the current terminal state as a structured Terminal State Tree with detected UI elements
- **terminal_wait_for** — Wait for text to appear, element to show, or terminal to be idle
- **terminal_press_key** — Press a special key or key combination (arrows, F-keys, Ctrl+X, etc.)
- **terminal_click** — Click on a UI element by its ref_id (navigates and activates)
- **terminal_session_resize** — Resize a terminal session to new dimensions

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mcp-server-terminal": {
    "command": "npx",
    "args": ["-y","mcp-server-terminal"]
  }
}
```

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/aybelatchane-mcp-server-terminal/readme_