一个基于 MCP (Model Context Protocol) 的 Electron 桌面终端应用,为 AI 助手提供安全的终端执行能力。让AI可以帮你运行远程机器的shell。
使用http协议
"terminal": {
"type": "http",
"url": "http://localhost:13000/mcp"
}
"terminal": {
"command": "npx",
"args": [
"mcp-remote",
"http://localhost:13000/mcp"
]
}



Hyper MCP Terminal 是一个现代化的桌面终端应用,集成了 MCP 协议支持,使 AI 助手能够安全地执行命令行操作。应用基于 Electron + TypeScript 构建,提供多标签页终端界面和实时通信能力。
- 🖥️ Electron 桌面应用: 跨平台桌面终端应用
- 📑 多标签页终端: 支持多个独立的终端会话
- 🤖 MCP 协议集成: 符合 Model Context Protocol 标准
- 🔄 实时通信: 基于 WebSocket 的实时终端交互
- 🎨 现代化界面: 基于 Ant Design 的美观界面
- ⚡ TypeScript: 完整的类型安全支持
electron/main.ts
: Electron 主进程入口electron/server.ts
: 内置 HTTP/WebSocket 服务器electron/index.mts
: MCP 服务器实现electron/window.ts
: 窗口管理和 IPC 处理frontend/
: React + TypeScript 前端界面
- 桌面框架: Electron
- 后端: Node.js + TypeScript + Express
- 前端: React + TypeScript + Ant Design
- 终端: xterm.js + node-pty
- 通信: Socket.IO + IPC
- 构建: Webpack + TypeScript Compiler
- Node.js 18+
- npm 或 pnpm
- C++ 编译环境(用于 node-pty 依赖)
- Python (Windows 用户)
npm install
# 启动开发服务器(后端)
npm run dev
# 启动前端开发监听
npm run dev:web
# 构建 TypeScript
npm run build
# 构建前端
npm run build:web
# 运行 Electron 应用
npm run electron
# 开发模式运行(启动服务器并打开应用)
npm run electron:dev
# 完整构建并打包
npm run electron:build
# 打包(不分发)
npm run electron:pack
hyper-mcp-terminal/
├── electron/ # 核心逻辑目录
│ ├── main.ts # Electron 主进程
│ ├── server.ts # HTTP/WebSocket 服务器
│ ├── index.mts # MCP 服务器
│ ├── commander.ts # 命令行参数处理
│ ├── shell.ts # 终端会话管理
│ ├── window.ts # 窗口管理
│ ├── preload.ts # 预加载脚本
│ └── dev.ts # 开发环境启动
├── frontend/ # React 前端界面
│ ├── index.tsx # 前端入口
│ ├── index.css # 样式文件
│ └── index.html # HTML 模板
├── build/ # 前端构建输出
├── dist/electron/ # TypeScript 编译输出
└── dist-electron/ # Electron 打包输出
应用设置自动保存在系统的应用数据目录中:
- macOS:
~/Library/Application Support/hyper-mcp-terminal/
- Windows:
%APPDATA%/hyper-mcp-terminal/
- Linux:
~/.config/hyper-mcp-terminal/
{
"server": {
"port": 13000
},
"terminal": {
"maxOutputTokens": 10000
},
"window": {
"width": 1200,
"height": 800,
"maximized": false
}
}
NODE_ENV
: 运行环境 (development/production)
- 自动保存: 所有设置更改自动保存到本地
- 窗口记忆: 应用会记住窗口位置、大小和最大化状态
- IPC 接口: 支持通过 IPC 调用动态修改设置
- 默认值回退: 无效设置自动回退到默认值
- Web 服务器端口可通过应用设置修改,默认: 3000
- MCP 服务器使用 stdio 传输
- 终端会话隔离
- 输出长度限制
- 超时保护
- 命令执行监控
- IPC 安全策略
node-pty 依赖需要 C++ 编译环境,请参考 官方文档 安装相关依赖:
Windows:
npm install --global windows-build-tools
macOS:
xcode-select --install
Linux (Ubuntu/Debian):
sudo apt-get install build-essential
node-pty 是一个原生模块,需要为 Electron 的 Node.js 版本重新编译。
开发环境解决方案:
# 方法1:使用electron-rebuild
npm run rebuild
# 方法2:重新安装node-pty
npm uninstall node-pty && npm install node-pty
# 方法3:手动重建
npx electron-rebuild
生产环境解决方案:
- 使用
electron-builder
打包时会自动处理原生模块重建 - 确保在目标平台上构建应用
注意事项:
- 开发时的 node-pty 版本问题不影响应用的核心功能(设置管理、窗口状态等)
- 终端功能需要 node-pty 正常工作
- 如果无法解决 node-pty 问题,可以考虑使用其他终端实现
在 Claude Desktop 的配置文件中添加:
{
"mcpServers": {
"hyper-mcp-terminal": {
"command": "path/to/hyper-mcp-terminal/dist/electron/index.mjs"
}
}
}
execute-command
: 在活跃终端中执行命令create-terminal-session
: 创建新的终端会话- 自动活跃终端检测和切换
npm run build
npm run build:web
npm run electron
npm run electron:build
构建产物将输出到 dist-electron/
目录。
- Fork 项目
- 创建功能分支:
git checkout -b feature/amazing-feature
- 提交更改:
git commit -m 'Add amazing feature'
- 推送分支:
git push origin feature/amazing-feature
- 创建 Pull Request
MIT License
- HyperChat - AI 聊天客户端
- Model Context Protocol - MCP 官方文档