# terminal-bridge-mcp

[![npm version](https://img.shields.io/badge/version-1.0.0-blue)](https://github.com/dividduang/terminal-bridge-mcp)
[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![MCP](https://img.shields.io/badge/Protocol-MCP-purple)](https://modelcontextprotocol.io)

An MCP (Model Context Protocol) server that bridges AI assistants to real terminal sessions — create, manage, read, and interact with persistent PTY processes.

Built with TypeScript, [node-pty](https://github.com/microsoft/node-pty), and the [MCP SDK](https://github.com/anthropics/model-context-protocol).

**[中文文档](README.zh-CN.md)**

---

## Why terminal-bridge-mcp?

AI coding assistants can write code, but they usually can't **run** it. `terminal-bridge-mcp` closes this gap by giving your AI a real terminal — not a sandboxed exec, but a full PTY session with persistent state.

This means your AI assistant can:

- **Start dev servers** and monitor their output in real time
- **Run tests** across multiple projects simultaneously
- **Manage long-running processes** (databases, queues, background workers)
- **Debug interactively** — send input to running programs, read responses
- **Monitor deployments** — tail logs, check health endpoints, watch for errors

All from within your existing MCP-compatible AI workflow (Claude Desktop, Cursor, Windsurf, etc.).

## Key Features

- **Multiple persistent sessions** — each terminal lives independently with its own state
- **Real PTY** — full pseudo-terminal support, not just `child_process.exec`
- **Regex search** — search across all sessions to find errors, warnings, or any pattern
- **ANSI stripping** — output is cleaned automatically for AI consumption
- **Output buffering** — up to 50,000 lines / 10MB per session, ring buffer with no memory leaks
- **Configurable** — custom working directory, environment variables, terminal dimensions

## Use Cases

### 1. Start and Monitor Dev Servers

Let your AI start a frontend dev server and check when it's ready:

```
> terminal_create {"command": "pnpm dev", "cwd": "/projects/my-app", "name": "frontend"}
→ Created session: term-1-abc123 (pid: 42000)

> terminal_read {"session_id": "term-1-abc123"}
→ VITE v7.3.1 ready in 2430ms
  ➜ Local: http://localhost:5173/
```

### 2. Run Backend Services with Virtual Environments

Activate a Python virtual environment and start the backend:

```
> terminal_create {"command": ".venv\\Scripts\\activate && fba run", "cwd": "/projects/backend", "name": "backend"}
→ Created session: term-2-def456 (pid: 43000)

> terminal_read {"session_id": "term-2-def456"}
→ API running at http://127.0.0.1:8000/api/v1
```

### 3. Run Tests in Parallel Across Projects

Start test runners for multiple services and monitor results:

```
> terminal_create {"command": "pytest -x", "cwd": "/projects/api", "name": "api-tests"}
> terminal_create {"command": "vitest run", "cwd": "/projects/web", "name": "web-tests"}
> terminal_create {"command": "go test ./...", "cwd": "/projects/worker", "name": "worker-tests"}

> terminal_search {"pattern": "PASS|FAIL|error|panic"}
→ [api-tests] 12 passed, 0 failed
  [web-tests] FAIL src/auth.test.ts
  [worker-tests] panic: nil pointer dereference
```

### 4. Manage Long-Running Infrastructure

Start databases, message queues, or background workers:

```
> terminal_create {"command": "docker compose up", "cwd": "/projects/my-stack", "name": "infra"}
> terminal_create {"command": "celery -A tasks worker", "cwd": "/projects/worker", "name": "celery"}

> terminal_read {"session_id": "term-infra", "filter": "ready|listening|started"}
→ postgres is ready to accept connections
  redis is ready to accept connections
```

### 5. Interactive Debugging

Send commands to a running REPL or CLI tool:

```
> terminal_create {"command": "python", "name": "repl"}

> terminal_write {"session_id": "term-repl", "text": "import pandas as pd"}
> terminal_write {"session_id": "term-repl", "text": "df = pd.read_csv('data.csv')"}
> terminal_write {"session_id": "term-repl", "text": "df.describe()"}
> terminal_read {"session_id": "term-repl"}
→        count  mean   std   min   max
  age    1000   35.2  12.1  18.0  89.0
```

### 6. Monitor Logs and Tail Output

Watch for specific patterns in running services:

```
> terminal_read {"session_id": "term-backend", "filter": "ERROR|WARN|exception", "lines": 200}
→ [ERROR] Connection refused to database replica
  [WARN] Retry attempt 3/5 for external API

> terminal_search {"pattern": "OOM|out of memory|killed"}
→ [worker] Process killed (OOM)
```

## Requirements

- Node.js >= 22.0.0
- Windows (uses PowerShell as the default shell)

## Install

```bash
git clone https://github.com/dividduang/terminal-bridge-mcp.git
cd terminal-bridge-mcp
npm install
npm run build
```

## Configure

Add to your MCP client configuration (`.mcp.json`, Claude Desktop settings, Cursor, Windsurf, etc.):

```json
{
  "mcpServers": {
    "terminal-bridge": {
      "command": "node",
      "args": ["path/to/terminal-bridge-mcp/dist/index.js"]
    }
  }
}
```

## Tools

### `terminal_create`

Create a new managed terminal session.

| Parameter | Type   | Default | Description                   |
| --------- | ------ | ------- | ----------------------------- |
| `command` | string | -       | Command to run on start       |
| `cwd`     | string | -       | Working directory             |
| `name`    | string | -       | Friendly name for the session |
| `env`     | object | -       | Additional environment vars   |
| `cols`    | number | 120     | Terminal columns              |
| `rows`    | number | 40      | Terminal rows                 |

Returns a session ID, PID, and session name.

### `terminal_list`

List all managed terminal sessions with their status, names, PIDs, and output line counts.

### `terminal_read`

Read output from a terminal session.

| Parameter    | Type    | Default | Description                      |
| ------------ | ------- | ------- | -------------------------------- |
| `session_id` | string  | -       | Session ID (required)            |
| `lines`      | number  | 100     | Number of recent lines to return |
| `filter`     | string  | -       | Regex pattern to filter lines    |
| `raw`        | boolean | false   | Include ANSI escape codes        |

### `terminal_search`

Search across terminal sessions for lines matching a regex pattern.

| Parameter     | Type   | Default | Description                |
| ------------- | ------ | ------- | -------------------------- |
| `pattern`     | string | -       | Regex pattern (required)   |
| `session_id`  | string | -       | Limit to a specific session|
| `max_results` | number | 50      | Maximum number of results  |

### `terminal_write`

Send input text to a running terminal session.

| Parameter     | Type    | Default | Description                 |
| ------------- | ------- | ------- | --------------------------- |
| `session_id`  | string  | -       | Session ID (required)       |
| `text`        | string  | -       | Text to send (required)     |
| `press_enter` | boolean | true    | Append Enter key after text |

### `terminal_kill`

Kill a terminal session and remove it from management.

| Parameter    | Type   | Description           |
| ------------ | ------ | --------------------- |
| `session_id` | string | Session ID (required) |

## Architecture

```
src/
├── index.ts          # MCP server and tool definitions
├── pty-manager.ts    # PTY process lifecycle management
├── output-buffer.ts  # Ring buffer for terminal output
└── types.ts          # TypeScript interfaces
```

- **OutputBuffer** — ring buffer that stores up to 50,000 lines / 10MB, strips ANSI codes, supports regex search
- **PtyManager** — manages multiple sessions, resolves shell to `pwsh.exe` or `powershell.exe`

## Comparison

| Feature                        | terminal-bridge-mcp | `child_process.exec` | IDE Terminal |
| ------------------------------ | ------------------- | -------------------- | ------------ |
| Full PTY support               | Yes                 | No                   | Yes          |
| AI can read output             | Yes                 | Manual               | No           |
| Multiple sessions              | Yes                 | One-shot             | Manual       |
| Regex search across sessions   | Yes                 | No                   | No           |
| Persistent state               | Yes                 | No                   | Yes          |
| Interactive input (write back) | Yes                 | No                   | Manual       |

## License

MIT