aybelatchane/mcp-server-terminal

npm version npm downloads License: MIT

MCP server enabling AI agents to interact with terminal applications through structured Terminal State Tree representation. Works with any AI assistant that supports the Model Context Protocol.

Installation

Via npm (Recommended)

npx mcp-server-terminal

Via GitHub Releases

Download pre-built binaries from Releases.

Build from Source

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

Configuration

Claude

Claude Code (CLI)

claude mcp add terminal -- npx mcp-server-terminal

Claude Desktop

Add to ~/.claude.json (macOS/Linux) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

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

---

OpenAI Codex

Codex CLI

codex mcp add terminal -- npx mcp-server-terminal

Codex Configuration File

Add to ~/.codex/config.toml:

[mcp_servers.terminal]
command = "npx"
args = ["mcp-server-terminal"]

---

Google Gemini

Gemini CLI

gemini mcp add terminal npx mcp-server-terminal

---

VS Code / GitHub Copilot

VS Code 1.101+ supports MCP. Add to your VS Code settings (settings.json):

{
  "mcp.servers": {
    "terminal": {
      "command": "npx",
      "args": ["mcp-server-terminal"]
    }
  }
}

---

Cursor

Add to ~/.cursor/mcp.json or .cursor/mcp.json in your project:

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

---

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

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

---

Zed

Add to your Zed settings (Preferences → Settings):

{
  "context_servers": {
    "terminal": {
      "command": {
        "path": "npx",
        "args": ["mcp-server-terminal"]
      }
    }
  }
}

---

Cline (VS Code Extension)

Click MCP Servers icon → Configure → Advanced MCP Settings, then add:

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

---

AWS Bedrock

Add to your Bedrock agent MCP configuration:

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

---

Other MCP Clients

For any MCP-compatible client, configure the server with:

• Command: npx
• Args: ["mcp-server-terminal"]

Or if using the binary directly:

• Command: terminal-mcp

Usage

Ask your AI agent:

• "Create a terminal session running htop"
• "Take a snapshot of the terminal"
• "Press the down arrow key"
• "Type 'ls -la' and press Enter"

MCP Tools

Tool	Description
terminal_session_create	Start a terminal session
terminal_session_list	List active sessions
terminal_session_close	Close a session
terminal_session_resize	Resize terminal dimensions
terminal_snapshot	Capture terminal state with UI elements
terminal_type	Type text into terminal
terminal_press_key	Press keys (arrows, F-keys, Ctrl+X)
terminal_click	Click on detected UI element
terminal_wait_for	Wait for text, element, or idle state
terminal_read_output	Read raw terminal output

Visual Mode

By default, sessions spawn a visible terminal window (xterm). For headless operation:

npx mcp-server-terminal --headless

Or in your MCP config:

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["mcp-server-terminal", "--headless"]
    }
  }
}

X11 Setup (Linux/WSL)

Visual mode requires X11. Add the DISPLAY environment variable to your MCP config:

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["mcp-server-terminal"],
      "env": {
        "DISPLAY": ":0"
      }
    }
  }
}

Logging

Set the RUST_LOG environment variable:

{
  "mcpServers": {
    "terminal": {
      "command": "npx",
      "args": ["mcp-server-terminal"],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

Log levels: error, warn, info, debug, trace

Logs go to stderr (stdout is reserved for MCP protocol).

Platform Support

Platform	Architecture	Status	Visual Mode
Linux	x64, arm64	✅ Full support	xterm + tmux
macOS	x64, arm64	✅ Full support	Terminal.app / iTerm2
Windows (WSL)	x64, arm64	✅ Full support	xterm + tmux (via X11)
Windows (native)	x64	⚠️ Headless only	Not supported

Windows users: Use WSL for full functionality including visual mode.

License

MIT