terminal-mcp

为你的 AI 配备真正的终端。持久会话。交互式程序。毫无限制。

问题所在

每款 AI 编码工具都会遇到同一个瓶颈：无法真正访问终端。

Claude Code 的 Bash 工具、GitHub Copilot 和 Codex 都在隔离的子进程中运行命令。每条命令都会重新启动，状态无法延续。这意味着：

• 无法建立 SSH 会话 - 不能连接远程服务并运行多条命令
• 无法使用 REPL - 不能交互式使用 Python、Node 或 Ruby 解释器
• 无法使用数据库 CLI - 不能维持 psql、mysql 或 redis-cli 连接
• 无法使用 TUI 应用 - 不能用方向键操作 htop、vim 或 fzf
• 无法运行长时间进程 - 不能监控构建、查看日志或运行开发服务

解决方案

terminal-mcp 为 AI Agent 提供真正的终端。持久的 PTY 会话可在多次工具调用之间持续存在。发送命令、读取输出、按下按键、操作 TUI——就像人在终端前操作一样。

uvx terminal-mcp

只需一条命令。兼容 Claude Code、Claude Desktop、VS Code、Cursor 和 Windsurf。

快速开始

1. 安装（30 秒）

# No install needed - run directly
uvx terminal-mcp

# Or install globally
pip install terminal-mcp

2. 连接到你的 AI 客户端

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

{
  "servers": {
    "terminal-mcp": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"]
    }
  }
}

3. 验证

session_exec  exec="echo hello from terminal-mcp"

可以用它做什么？

通过 SSH 登录远程服务

session_create   command="ssh [email protected]"   label="prod"
session_interact session_id="a1b2c3d4"  input="df -h"  wait_for="\$"
session_interact session_id="a1b2c3d4"  input="docker ps"  wait_for="\$"
session_close    session_id="a1b2c3d4"

运行交互式 REPL

session_create   command="python3"  label="python"
session_interact session_id="e5f6g7h8"  input="import pandas as pd"  wait_for=">>>"
session_interact session_id="e5f6g7h8"  input="df = pd.read_csv('data.csv')"  wait_for=">>>"
session_interact session_id="e5f6g7h8"  input="df.describe()"  wait_for=">>>"
session_close    session_id="e5f6g7h8"

查询数据库

session_create   command="psql -U admin mydb"  label="db"
session_interact session_id="x1y2z3w4"  input="SELECT count(*) FROM users;"  wait_for="row"
session_interact session_id="x1y2z3w4"  input="\dt"  wait_for="#"
session_close    session_id="x1y2z3w4"

操作 TUI 应用

session_create   command="htop"  label="monitor"
session_read     session_id="a1b2c3d4"
# Auto-detects TUI, returns screen snapshot

session_send     session_id="a1b2c3d4"  key="F6"
session_read     session_id="a1b2c3d4"  mode="diff"
# Returns only changed lines - saves tokens

session_send     session_id="a1b2c3d4"  key="F10"
session_close    session_id="a1b2c3d4"

监控长时间运行的构建

session_create   command="bash"  label="build"
session_send     session_id="a1b2c3d4"  input="npm run build"
session_wait_for session_id="a1b2c3d4"  pattern="Build complete|ERROR"  timeout=120

运行一次性命令

session_exec  exec="git log --oneline -10"
session_exec  exec="docker compose ps"  timeout=10

功能一览

工具参考

terminal-mcp 提供 9 个 MCP 工具。完整详情请参阅 docs/tools.md。

架构

flowchart LR
    Client[AI Client] -->|MCP JSON-RPC| Server[terminal-mcp]
    Server --> SM[Session Manager]
    SM --> S1[PTY 1: bash]
    SM --> S2[PTY 2: python3]
    SM --> S3[PTY 3: ssh user@host]
    S1 & S2 & S3 -.->|PTY output| Reader[Reader Thread]
    Reader -.->|buffer| Server

每个会话都由 pexpect.spawn（Windows 上为 PopenSpawn）通过真正的 PTY 支持。完整的架构详情请参阅 docs/architecture.md。

配置

所有设置都可通过 TERMINAL_MCP_* 环境变量进行配置。完整参考请参阅 docs/configuration.md。

使用自定义设置的示例：

{
  "mcpServers": {
    "terminal": {
      "command": "uvx",
      "args": ["terminal-mcp"],
      "env": {
        "TERMINAL_MCP_MAX_SESSIONS": "20",
        "TERMINAL_MCP_IDLE_TIMEOUT": "3600",
        "TERMINAL_MCP_TRUNCATION_MODE": "head_tail"
      }
    }
  }
}

文档

Supported Clients

Running Tests

pip install -e ".[dev]"
pytest tests/ -v

Contributing

Contributions welcome! See docs/contributing.md for guidelines.

License

MIT