mcp -terminal

This MCP server enables AI agents to interact with a local terminal through a structured Terminal State Tree representation. It exposes a set of MCP tools that allow you to start and manage terminal sessions, read and modify terminal state, and simulate user interactions. The primary tools include creating a terminal session, listing active sessions, resizing the terminal, capturing a terminal snapshot with UI elements, typing text, sending key presses (including navigation keys), clicking on detected UI elements, waiting for specific text or idle states, and reading raw terminal output. To use it, configure your MCP client to connect to the server (via the npx command as shown in the configuration examples), then issue commands through your agent to manipulate terminal sessions and drive interactions as if you were operating a real terminal.

Prerequisites:

• Node.js and npm installed on your machine (to use npx).
• Alternatively, you can build from source (Rust/Cargo) if you prefer a local binary, as described below.

Option 1: Run via npm (recommended)

1. Ensure Node.js and npm are installed.
2. Start the MCP server directly using npx:

npx mcp-server-terminal

Option 2: Build from source (Rust)

1. Install Rust and Cargo from https://rustup.rs/
2. Clone the repository and build the release binary:

git clone https://github.com/aybelatchane/mcp-server-terminal.git
cd mcp-server-terminal
cargo build --release
# Binary: ./target/release/terminal-mcp

3. Run the binary directly if you built it:

./target/release/terminal-mcp

Option 3: Download pre-built binaries

• Visit the Releases page at https://github.com/aybelatchane/mcp-server-terminal/releases and download the appropriate binary for your platform, then run it according to the provided instructions.

Tips and common considerations:

• Visual mode vs headless: By default sessions spawn a visible terminal window. To run headless, start with --headless or configure your MCP client to pass that flag. In MCP config, you can add --headless to the command args.
• X11 requirements: If you enable visual mode on Linux/WSL, you may need X11 and the DISPLAY environment variable. Example env: { "DISPLAY": ":0" } in your MCP config.
• Logging: You can set RUST_LOG to control log verbosity when running the server. Example: { "mcpServers": { "terminal": { "command": "npx", "args": ["mcp-server-terminal"], "env": { "RUST_LOG": "info" } } } }.
• Platform support: The server is designed to work across Linux, macOS, and Windows (via WSL or native with headless support). Visual mode behavior and windowing depend on the platform and X11 availability.
• MCP client compatibility: Any MCP client that adheres to the Model Context Protocol can be configured to use the terminal server. The standard approach is to set command to npx and args to ["mcp-server-terminal"]; you can also use the binary directly if preferred.