terminal-bridge-mcp

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.

[中文文档](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

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.

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.

terminal_search

Search across terminal sessions for lines matching a regex pattern.

terminal_write

Send input text to a running terminal session.

terminal_kill

Kill a terminal session and remove it from management.

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

License

MIT