terminal-bridge-mcp

![npm version](https://github.com/dividduang/terminal-bridge-mcp) ![license](LICENSE) ![MCP](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, and the MCP SDK.

中文文档

---

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

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.):

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

terminal-bridge-mcp