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

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

### Option 2: Install from a local clone

```bash
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`):

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

Or if installed globally:

```json
{
  "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