Terminal MCP

Cross-platform MCP server for managing visible terminal sessions.

Features

• Cross-platform: Supports macOS, Windows, Linux, and WSL
• Visible terminals: Opens real terminal windows that users can see and interact with
• Multiple sessions: Manage multiple terminal sessions simultaneously
• Auto-cleanup: Automatically closes terminals when MCP server stops

Installation

Since this package is not published on PyPI, install it directly from the repository:

Option 1: Install from GitHub (recommended)

uv pip install "git+https://github.com/Hor1zonZzz/terminal-mcp.git"

Option 2: Install from a local clone

git clone https://github.com/Hor1zonZzz/terminal-mcp.git
cd terminal-mcp
uv pip install -e .

Usage

Claude Desktop Configuration

Add to your Claude Desktop config (claude_desktop_config.json):

{
  "mcpServers": {
    "terminal": {
      "command": "uv",
      "args": ["run", "terminal-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "terminal": {
      "command": "terminal-mcp"
    }
  }
}

Available Tools

terminal_create_or_get

Create a new visible terminal window or get an existing one by name.

Parameters:

• name (optional): Name for the terminal session
• working_dir (optional): Working directory for the terminal

Returns: Session ID, name, platform, and status message

terminal_send_input

Send input (command or text) to a terminal.

Parameters:

• session_id: The terminal session ID
• text: The command/text to send

terminal_get_output

Get the output from a terminal.

Parameters:

• session_id: The terminal session ID
• lines (optional): Number of lines to retrieve (default: 100, max: 1000)

terminal_list

List all active terminal sessions.

terminal_close

Close a terminal session.

Parameters:

• session_id: The terminal session ID to close

Platform Support

Platform	Terminal Used
macOS	Terminal.app (via AppleScript)
Windows	Windows Terminal (wt.exe) or cmd.exe
Linux	gnome-terminal, konsole, xfce4-terminal, xterm, etc.
WSL	Windows Terminal from WSL

How It Works

1. Terminal Creation: Opens a real terminal window using platform-specific methods
2. Communication: Uses named pipes (Unix) or file polling (Windows) for bidirectional communication
3. Output Capture: Logs terminal output to temporary files for retrieval
4. Cleanup: Automatically closes all terminals when the MCP server stops (via atexit and signal handlers)

License

MIT