使用说明
🧩 终端MCP
一个生产级模型上下文协议（MCP）服务器 PTY原生执行 专为 光标IDE为Cursor的人工智能助手和人类提供统一的交互式终端，实现共享终端环境中的无缝命令执行。
✨ 特性
- PTY原生执行 -命令直接在PTY终端中运行（单一事实来源）
- 多项目支持 -按需PTY，每个项目根共享状态
- 真实环境 -AWS SSO、导出、凭据均正常工作
- 共享可见性 -你和AI助手看到的是完全相同的终端
- HTTP传输 -部署在任何地方，从任何机器访问
- WebSocket支持 -实时终端连接和监控
- 上下文感知执行 -在执行之前提供终端上下文的增强工具
- 后台模式 -使用CLI管理作为后台服务运行
- 平滑关闭 -正确清理PTY流程和连接
📋 先决条件
- Node.js（v16或更高版本）
- 支持PTY的类Unix系统（macOS、Linux）
🚀 快速开始
安装
npm install -g terminal-mcp
或者克隆并在本地安装：
git clone https://github.com/yourusername/terminal-mcp.git
cd terminal-mcp
npm install
基本用法
- 启动守护进程：
npm run daemon
# Or run in background:
npm run daemon:bg
- 配置光标MCP设置(光标→ 设置→ 特性→ 模型上下文协议):
{
"mcpServers": {
"pty-terminal": {
"url": "http://localhost:3333/mcp"
}
}
}
- 重新启动游标
CLI命令
# Start daemon
npm run daemon
# Start daemon in background
npm run daemon:bg
# Check status
npm run status
# List active terminals
npm run list
# Stop daemon
npm run stop
🏗️ 建筑学
Cursor/AI Assistant
│
▼
MCP HTTP Server (Express)
│
├─ HTTP Transport (JSON + SSE)
├─ WebSocket Transport (real-time)
│
▼
PTY Manager
│
├─ On-demand PTY creation per project root
├─ Shared PTY state (env vars, cwd, auth tokens)
├─ Terminal Event Journal (output history)
│
▼
PTY Processes (node-pty)
│
▼
Real Shell Environment
关键部件：
- PTY经理：管理多个PTY实例，每个项目根目录一个
- 终端事件日志：捕获并存储终端输出历史记录
- MCP工具:
execute,execute2,interrupt,list_terminals,read_terminal - HTTP 服务器：基于Express的服务器，支持MCP传输和WebSocket
📝 运作原理
- MCP服务器启动并为默认项目根创建默认PTY
- AI助手通过MCP发送命令
execute或execute2工具 - 命令在相应的PTY中执行（基于项目根）
- 输出通过PTY事件监听器捕获并存储在事件日志中
- 结果通过MCP返回给AI助手
- 人类可以通过WebSocket或CLI连接到终端以监视活动
🎯 使用示例
人工智能助理（自动）
AI助手会自动使用此终端执行所有命令。只要问：
- “运行测试”
- “安装依赖项”
- “启动服务器”
- “检查日志”
- “构建项目”
人类（手动终端访问）
通过WebSocket连接到终端：
# Using the CLI
mcp-terminal attach
# Or connect directly via WebSocket
wscat -c ws://localhost:3333/attach?projectRoot=/path/to/project
🔧 配置
环境变量
PORT：服务器端口（默认值：3333）PROJECT_ROOT：默认项目根路径（默认：主目录）SHELL：用于PTY的Shell（默认值：/bin/zsh)
项目专用码头
服务器会自动为不同的项目根创建单独的PTY实例。调用MCP工具时指定项目根：
{
"command": "npm test",
"projectRoot": "/path/to/my/project"
}
🚀 部署
码头工人
docker build -t terminal-mcp .
docker run -p 3333:3333 \
-e PROJECT_ROOT=/app \
-e PORT=3333 \
terminal-mcp
云平台
工作内容：
- AWS EC2 / GCP虚拟机 / 数字海洋
- 云运行 / Fly.io / 渲染
- Docker Compose / Kubernetes
全部支持HTTP+SSE传输。
🔒 安全
重要安全注意事项：
- ⚠️ 默认情况下不进行身份验证 -添加生产使用的身份验证
- ⚠️ 无速率限制 -对公共部署实施速率限制
- ⚠️ 完全命令执行权限 -命令以与守护程序用户相同的权限运行
对于生产，添加：
- API密钥头验证
- IP地址列表
- 命令denylist/filtering
- 只读模式切换
- TLS/HTTPS加密
看 安全.md 了解更多信息。
🧪 发展
设置
git clone https://github.com/yourusername/terminal-mcp.git
cd terminal-mcp
npm install
运行测试
npm test
代码质量
# Linting (if configured)
npm run lint
# Formatting (if configured)
npm run format
看 贡献.md 详细的开发指南。
📚 API 参考
MCP工具
execute
在共享PTY终端中执行命令。
参数：
command（必需）：要执行的Shell命令projectRoot（可选）：项目根路径
execute2
上下文感知执行，在执行之前显示终端历史记录。
参数：
command（必需）：要执行的Shell命令projectRoot（可选）：项目根路径contextChars（可选）：要显示的上下文的最大字符数（默认值：2000）
interrupt
发送Ctrl+C以中断当前正在运行的命令。
参数：
projectRoot（可选）：项目根路径
list_terminals
列出服务器管理的所有活动PTY终端。
read_terminal
在不执行任何命令的情况下读取终端输出历史记录。
参数：
projectRoot（可选）：项目根路径maxChars（可选）：返回的最大字符数（默认值：8000）mode（可选）：读取模式-tail,since_last，或full（默认值：tail)
HTTP端点
GET /health-健康检查端点POST /mcp-MCP协议端点GET /terminals-列出活动终端WS /attach-用于终端连接的WebSocket端点
🛠️ 故障排除
未找到终端
服务器根据需要自动创建PTY实例。如果您遇到问题：
- 检查守护进程是否正在运行：
npm run status - 验证项目根路径是否存在
- 检查服务器日志是否有错误
命令未执行
确保：
- MCP服务器在游标设置中配置正确
- PROJECT_ROOT路径是绝对正确的
- 配置后您已重新启动Cursor
- 守护进程正在运行且可访问
检查活动端子
npm run list
# Or via HTTP:
curl http://localhost:3333/terminals
🤝 贡献
我们欢迎捐款！请参阅 贡献.md 作为指导方针。
📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
📞 支持
制作于❤️ 对于开源社区