Log inSubmit server
MCP Server Terminal logo

MCP Server Terminal

by aybelatchane

Controls interactive terminal applications through MCP sessions, structured snapshots, keyboard input, clicks, waits, and resizing.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install MCP Server Terminal

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "aybelatchane-mcp-server-terminal": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-server-terminal"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Automated check passed— started and listed 10 tools correctly (1mo ago).

Overview

The aybelatchane/mcp-server-terminal MCP server lets AI agents operate terminal applications through MCP tools and structured Terminal State Tree snapshots. It can create and manage sessions, type text, send keys, read output, detect interface elements, wait for state changes, click detected elements, and resize terminals. Use it for TUI and CLI workflows where raw shell execution is insufficient, including interactive programs such as htop. Sessions run with visible terminal windows by default or in headless mode when configured.

Use cases

  • Operate interactive TUI applications
  • Inspect terminal state as structured elements
  • Automate CLI workflows requiring keyboard input
  • Run headless terminal sessions in CI environments

Key features

  • Structured Terminal State Tree snapshots
  • Interactive terminal session management
  • Keyboard, text input, and element clicking
  • Wait conditions for text, elements, and idle state
  • Visible and headless execution modes
  • Terminal resizing and raw output reading

Tools10

What MCP Server Terminal lets your agent do. Expand a tool for its parameters.

Verified live~1.5k tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

18/18 checks healthy over the last 79d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 10d ago via OSV.dev · mcp-server-terminal (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars21Stargazers on the source repository.
npm downloads168Package downloads in the last 30 days.
Last commit9mo agoMost recent push to the default branch.
Availability100%Our rolling endpoint + install checks that succeeded.
Install checkPassedOur sandbox started it and listed its tools.
Tools exposed10Callable tools this server registers over MCP.
Directory activity4 viewsConfig copies, upvotes, and views on AllMCPs.

How MCP Server Terminal works

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

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about MCP Server Terminal

Run it through npm with npx using the mcp-server-terminal package, or download a pre-built release binary. The source can also be built with Cargo.

Yes. The README provides Claude Desktop configuration using npx and the mcp-server-terminal package.

Yes. Start it with the --headless option. Native Windows is documented as headless-only; visual mode on Linux and WSL requires X11 and DISPLAY.

It provides tools for creating and managing sessions, reading output, taking structured snapshots, typing text, pressing keys, clicking detected elements, waiting for terminal conditions, and resizing sessions.

Related MCP servers

All in Coding Agents All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMCP Server Terminal AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/aybelatchane-mcp-server-terminal?style=directory)](https://allmcps.com/mcp/aybelatchane-mcp-server-terminal)
HTML Embed
<a href="https://allmcps.com/mcp/aybelatchane-mcp-server-terminal"><img src="https://allmcps.com/api/badge/aybelatchane-mcp-server-terminal?style=directory" alt="MCP Server Terminal on AllMCPs" /></a>