# Terminal MCP Server

An MCP (Model Context Protocol) server that allows AI agents to create and interact with isolated tmux terminal sessions in real time.

## Features

- **Create sessions** — spin up isolated tmux terminals on demand
- **Send commands** — execute shell commands in any session
- **Read output** — capture live terminal screen content
- **Interrupt** — send Ctrl+C to running processes
- **Close sessions** — clean up when done

## Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `create_session` | Create a new isolated tmux terminal session | `session_id` (optional string) |
| `send_keys` | Send a command to a specific tmux session | `session_id` (string), `command` (string) |
| `get_screen` | Return the current screen output of a tmux session | `session_id` (string) |
| `interrupt` | Send Ctrl+C to a running tmux session | `session_id` (string) |
| `close_session` | Kill a tmux terminal session | `session_id` (string) |

## Requirements

- Python 3.10+
- tmux
- `mcp` package (`mcp>=1.28.0`)

## Installation

```bash
pip install -r requirements.txt
```

## Usage

### Run the server

```bash
python Server.py
```

### Configure in opencode

Add to your `opencode.json`:

```json
{
  "mcp": {
    "terminal": {
      "type": "local",
      "command": ["python", "/path/to/Server.py"],
      "enabled": true
    }
  }
}
```

### Test manually

```python
from mcp import StdioClient
import asyncio

async def test():
    async with StdioClient("python Server.py") as client:
        result = await client.call_tool("create_session", {"session_id": "test-1"})
        print(result)
        result = await client.call_tool("send_keys", {"session_id": "test-1", "command": "echo hello"})
        screen = await client.call_tool("get_screen", {"session_id": "test-1"})
        print(screen)

asyncio.run(test())
```

## How it works

Each session is backed by a tmux window. Commands are sent via `tmux send-keys`, output is captured via `tmux capture-pane`. Sessions persist until explicitly closed.

You can attach to any running session to watch the AI interact in real time:

```bash
tmux attach -t <session_id>
```