MCP Shellkeeper

🚀 🐚 MCP ShellKeeper

MCP ShellKeeper 能够让 AI 助手拥有持久的终端会话和文件传输能力。借助它，AI 助手可以通过 SSH 连接服务器、执行命令以及传输文件，打破了无状态操作的限制。

🚀 快速开始

要使用 MCP ShellKeeper，你可以按照以下步骤进行安装和配置：

npm install -g mcp-shellkeeper

配置

不同的 AI 助手有不同的配置方式：

• Cursor： 打开设置 JSON 文件（通过 Cmd+Shift+P → Preferences: Open Settings），添加以下内容：

  {
    "mcpServers": {
      "shellkeeper": {
        "command": "npx",
        "args": ["-y", "mcp-shellkeeper"]
      }
    }
  }
  

• Claude Code： 在配置文件 ~/.config/claude/config.json 中添加以下内容：

  {
    "mcpServers": {
      "shellkeeper": {
        "command": "npx",
        "args": ["-y", "mcp-shellkeeper"]
      }
    }
  }
  

• VS Code (Cline)： 打开设置 JSON 文件，添加以下内容：

  {
    "cline.mcpServers": {
      "shellkeeper": {
        "command": "npx",
        "args": ["-y", "mcp-shellkeeper"]
      }
    }
  }
  

重新启动你的 AI 助手，即可开始使用！🎉

✨ 主要特性

🔄 有状态执行

传统的 AI 执行命令是无状态的，例如：

你: "SSH 连接到服务器"
AI: ❌ 命令一直挂起

你: "列出文件"
AI: ❌ 在本地执行，而不是服务器上

而使用 ShellKeeper 后，AI 可以实现有状态执行：

你: "连接到我的服务器"
AI: ✅ 建立 SSH 会话

你: "有哪些文件？"
AI: ✅ 列出服务器上的文件

你: "进入日志文件夹"
AI: ✅ 切换到 /var/log

你: "显示最近的错误"
AI: ✅ 显示日志内容

AI 可以在你的问题之间保持完整的上下文！

🎯 持久会话

使用 ShellKeeper 可以实现自然的对话流程：

你: "SSH 连接到生产服务器"
AI: ✅ 连接到 prod-01
    会话: prod-01

你: "还剩多少磁盘空间？"
AI: ✅ 可用空间 45GB
    (同一个会话，无需重新认证)

你: "显示今天的日志"
AI: ✅ 显示日志...
    (同一个会话继续)

你: "重启 API 服务"
AI: ✅ 服务已重启
    (仍然是同一个会话！)

AI 可以记住所有信息，包括：

• ✅ 你的 SSH 连接
• ✅ 当前目录
• ✅ 环境变量
• ✅ 所有先前的上下文

📁 无缝文件传输

你可以用自然语言要求 AI 进行文件传输：

你: "将我的配置文件上传到服务器"
AI: ✅ 已上传 config.json
    /app/config/config.json

---

你: "下载错误日志"
AI: ✅ 已下载 app.log
    保存到 ./logs/app.log

---

你: "获取数据库备份"
AI: ✅ 已下载 backup.sql
    (即使通过 SSH 跳转！)

文件传输功能具有以下特点：

• ✅ 可通过任何 SSH 会话进行
• ✅ 支持多个跳转主机
• ✅ 最大支持 10MB 的文件
• ✅ 支持二进制和文本文件

💻 使用示例

基础用法

以下是一个通过 AI 助手使用 ShellKeeper 进行服务器调试的真实示例：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

👤 你询问:
   "调试生产服务器 prod-server-01 上的缓慢 API"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 AI 执行:

   [正在连接...]
   → ssh user@prod-server-01
   ✅ 已连接到 prod-server-01

   [正在调查进程...]
   → ps aux | grep api
   📊 找到 API 进程: PID 1234，占用 98% CPU

   [正在检查日志...]
   → cd /var/log/api && tail -n 100 error.log
   🔍 错误: /api/v1/users 端点存在内存泄漏

   [正在下载进行分析...]
   → 下载: /var/log/api/error.log → ./local-debug/
   ✅ 已下载 2.4MB (分析发现 500 多个内存错误)

   [正在应用修复...]
   → 上传: ./fixed-config.yml → /app/config/
   ✅ 已上传新的速率限制配置

   [正在重启服务...]
   → systemctl restart api-service
   → systemctl status api-service
   ✅ 服务已重启，CPU 现在降至 12%

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🤖 AI 回复:
   "已修复！API 在用户端点存在内存泄漏。

   • 下载日志并发现 500 多个内存分配错误
   • 应用了速率限制配置
   • 重启服务 - CPU 从 98% 降至 12%
   • 所有操作都在一个持久会话中完成"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✨ 所有操作都在一个会话中完成，无需重新认证！✨

高级用法

AI 会自动使用以下工具，但你也可以参考这些工具进行高级使用：

💡 提示：AI 会根据你的自然语言请求自动处理这些工具！

📚 详细文档

💡 使用场景

所有操作都可以通过与 AI 的自然对话完成！无需编写脚本，也无需手动进行 SSH 操作。

🔧 技术细节

持久会话

• 使用 PTY（伪终端）进行完整的 TTY 模拟，实现状态持久化。
• 智能标记可自动检测命令完成情况。
• 捕获退出代码以进行错误检测。
• 输出经过解析，无 ANSI 代码。

文件传输

• 通过现有的 SSH 会话使用 Base64 编码进行文件传输（无需单独的 SCP/SFTP）。
• 支持通过跳转主机进行传输，无需重新认证。
• 最大支持 10MB 的文件，超时时间为 5 分钟（如果传输速度快，会提前完成）。

🔒 安全最佳实践

✅ 建议操作：

• 使用 SSH 密钥认证（而非密码）：ssh-keygen -t ed25519
• 通过堡垒机跳转连接到生产环境：ssh -J bastion.com user@prod
• 限制文件上传目标（避免 /etc、/root、.ssh/）
• 使用只读账户进行调查
• 任务完成后清理会话
• 审计所有 AI 操作

❌ 避免操作：

• 在命令或配置中存储密码
• 将不可信的文件上传到生产环境
• 在未加密的情况下下载敏感数据
• 在未验证的情况下运行破坏性命令
• 授予不必要的权限

🐛 故障排除

// 增加长时间运行命令的超时时间
terminal_execute({
  command: "npm install",
  timeout: 120000  // 2 分钟
})

// 检查 SSH 密钥是否正确设置
ssh -v user@server

# 设置无密码认证
ssh-keygen -t ed25519
ssh-copy-id user@server

# 验证
ssh user@server "echo Success"

// 首先检查是否在 SSH 会话中
terminal_execute({ command: "pwd" })  // 验证你是否在远程服务器上

// 确保远程目录存在
terminal_execute({ command: "mkdir -p /app/uploads" })

// 然后上传
terminal_upload({ local_path: "file.txt", remote_path: "/app/uploads/file.txt" })

// 验证远程文件是否存在
terminal_execute({ command: "ls -lh /path/to/file" })

// 检查权限
terminal_execute({ command: "cat /path/to/file | wc -l" })

// 尝试使用绝对路径下载
terminal_download({ remote_path: "/full/path/to/file", local_path: "./" })

// 列出所有会话
terminal_list_sessions()

// 关闭有问题的会话
terminal_close_session({ session_id: "stuck-session" })

// 创建新会话
terminal_new_session({ session_id: "new-session" })

🧪 开发

# 克隆仓库
git clone https://github.com/tranhuucanh/mcp-shellkeeper.git
cd mcp-shellkeeper

# 安装依赖
npm install

# 构建
npm run build

# 在本地使用 stdio 传输进行测试
node dist/index.js

# 使用 MCP Inspector 进行测试
npm run inspector

🤝 贡献

欢迎贡献代码！帮助我们让 AI 辅助服务器管理变得更好。

1. 分叉仓库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情请参阅 LICENSE 文件。

你可以：

• ✅ 商业使用
• ✅ 修改
• ✅ 分发
• ✅ 私人使用

🙏 致谢

• 基于 Model Context Protocol SDK 构建
• 使用 node-pty 进行终端模拟
• 受 AI 工作流中有状态命令执行需求的启发

📞 支持

• 问题反馈：GitHub Issues
• 讨论交流：GitHub Discussions
• MCP 社区：Discord