JinDaGe - mcp-shellkeeper MCP Details

article

README

🚀 🐚 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 会自动使用以下工具，但你也可以参考这些工具进行高级使用： | 工具 | 用途 | 主要特性 | |------|---------|--------------| | terminal_execute | 在持久会话中运行命令 | 可配置超时时间、捕获退出代码、输出干净 | | terminal_upload_file | 将本地文件上传到远程服务器（最大 10MB） | 自动检测目录、处理重复文件、支持通过 SSH 上传 | | terminal_download_file | 从远程服务器下载文件到本地（最大 10MB） | 自动创建目录、保留权限、验证文件完整性 | | terminal_new_session | 创建隔离的会话 | 支持并行操作、独立的环境 | | terminal_list_sessions | 查看所有活动会话 | 显示状态、运行时间、最后执行的命令 | | terminal_close_session | 清理会话 | 任务完成后释放资源 | | terminal_get_buffer | 调试原始输出 | 有助于故障排除 |

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

📚 详细文档

💡 使用场景

| 场景 | 你可以询问的内容 | AI 执行的操作 | |----------|-------------|--------------| | 🔍 调试生产环境 | "为什么生产 API 这么慢？" | SSH 连接 → 检查 CPU/内存 → 下载日志 → 分析 → 上传修复 → 重启 | | 🚀 部署更新 | "将 v2.0 部署到测试环境" | SSH 连接 → 备份 → 上传文件 → 迁移数据库 → 重启 → 验证 | | 🔧 更新配置 | "更新 Web 服务器上的 SSL 证书" | SSH 连接 → 下载旧证书 → 上传新证书 → 测试 → 重新加载 nginx | | 🗄️ 备份数据库 | "将生产数据库备份到本地" | 通过堡垒机 SSH 连接 → 转储数据库 → 压缩 → 下载 → 验证 | | 📊 分析日志 | "查找今天所有的 500 错误" | SSH 连接 → 解析日志 → 下载 → 本地分析 → 报告模式 | | 🔄 批量操作 | "更新所有服务器上的配置" | 并行会话 → 上传 → 重启 → 下载结果 |

所有操作都可以通过与 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 要求输入密码

# 设置无密码认证
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 辅助服务器管理变得更好。

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

📄 许可证

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

你可以：

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

🙏 致谢

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

📞 支持

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

为 AI 开发者社区用心打造 ❤️

有状态执行 + 文件传输 = 无限可能

⬆ 返回顶部

mcp-shellkeeper