星战科技xingzhan.cloud
返回市场
MCP壳守护者

MCP壳守护者

作者：tranhuucanh23 星标更新：2025-11-11
安装使用来源：spider==github.com

项目介绍

🐚 MCP ShellKeeper

<div align="center">

持久化的终端会话 + 文件传输功能，适用于AI助手

通过AI助手进行SSH连接到服务器，执行命令，传输文件——所有操作都无需担心状态问题。

License: MIT Node Version MCP npm npm 下载量 询问DeepWiki

实际案例 • 安装 • 核心功能 • 应用场景 • 工具

</div>

🎯 需要解决的问题

像Cursor这样的AI助手执行命令是无状态的——每个命令都在一个全新的环境中运行：

❌ ssh user@server                          # 挂起，没有输出直到退出
❌ 无法在SSH后运行命令
❌ 每个命令从头开始
❌ 无法传输文件到/从服务器
❌ 每次操作都需要重新认证

✨ 解决方案

ShellKeeper将AI助手转变为具有持久会话和文件传输能力的状态化操作者。

🚀 核心功能

<table> <tr> <td width="33%" align="left">

🔄 状态化执行

传统AI（无状态）

您: "SSH到服务器"
AI: ❌ 命令挂起

您: "列出文件"
AI: ❌ 在本地运行，不在服务器上

ShellKeeper（有状态）

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

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

您: "进入日志文件夹"
AI: ✅ 更改到/var/log

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

AI在整个对话中保持上下文！

</td> <td width="33%" align="left">

🎯 持久会话

自然对话流程

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

您: "剩余多少磁盘空间？"
AI: ✅ 剩余45GB
    （同一会话，无需重新认证）

您: "显示今天的日志"
AI: ✅ 显示日志...
    （同一会话继续）

您: "重启API服务"
AI: ✅ 服务已重启
    （仍然是同一会话！）

AI记住一切：

  • ✅ 您的SSH连接
  • ✅ 当前目录
  • ✅ 环境变量
  • ✅ 所有之前的上下文
</td> <td width="33%" align="left">

📁 无缝文件传输

只需用自然语言请求

您: "上传我的配置到服务器"

AI: ✅ 已上传config.json
    /app/config/config.json

---

您: "下载错误日志"

AI: ✅ 已下载app.log
    保存到./logs/app.log

---

您: "获取数据库备份"

AI: ✅ 已下载backup.sql
    （即使通过SSH跳转！）

它就这么简单：

  • ✅ 通过任何SSH会话
  • ✅ 多个跳转主机
  • ✅ 最大10MB文件
  • ✅ 二进制和文本文件
</td> </tr> </table>

🎬 实际案例

观看如何将自然对话变成自动化操作：

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

👤 您提问：
   "调试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 1100 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%
   • 所有操作在一个持久会话中完成"

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

✨ 全部在一个会话中完成，无需重新认证！ ✨

📦 安装

npm install -g mcp-shellkeeper

配置

<table> <tr> <td width="33%">

Cursor

设置JSON：

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

（Cmd+Shift+P → Preferences: Open Settings）

</td> <td width="33%">

Claude Code

配置文件：

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

（~/.config/claude/config.json）

</td> <td width="33%">

VS Code (Cline)

设置JSON：

{
  "cline.mcpServers": {
    "shellkeeper": {
      "command": "npx",
      "args": ["-y", "mcp-shellkeeper"]
    }
  }
}
</td> </tr> </table>

重启您的AI助手，即可准备就绪！ 🎉

💡 应用场景

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

全部通过与您的AI助手的自然对话完成！ 不需要脚本，不需要手动SSH切换。

📖 可用工具

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根据您的自然语言请求自动处理这些工具！

🔒 安全最佳实践

✅ 应该做：

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

❌ 不应该做：

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

🛠️ 工作原理

持久会话：

  • 使用PTY（伪终端）进行完整的TTY仿真，并保持状态
  • 智能标记自动检测命令完成
  • 捕获退出码以检测错误
  • 解析输出干净（无ANSI代码）

文件传输：

  • 通过现有SSH会话进行Base64编码（无需单独的SCP/SFTP）
  • 通过跳转主机工作，无需重新认证
  • 最大10MB，5分钟超时（如果更快则提前完成）

🐛 故障排除

<details> <summary><b>命令超时或挂起</b></summary> 
// 增加长时间运行命令的超时时间
terminal_execute({
  command: "npm install",
  timeout: 120000  // 2分钟
})

// 检查SSH密钥是否正确设置
ssh -v user@server
</details> <details> <summary><b>SSH请求密码</b></summary> 
# 设置无密码认证
ssh-keygen -t ed25519
ssh-copy-id user@server

# 验证
ssh user@server "echo 成功"
</details> <details> <summary><b>文件上传失败</b></summary> 
// 首先检查是否在SSH会话中
terminal_execute({ command: "pwd" })  // 验证您在远程服务器上

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

// 然后上传
terminal_upload({ local_path: "file.txt", remote_path: "/app/uploads/file.txt" })
</details> <details> <summary><b>文件下载失败</b></summary> 
// 验证远程文件是否存在
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: "./" })
</details> <details> <summary><b>会话变得无响应</b></summary> 
// 列出所有会话
terminal_list_sessions()

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

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

🧪 开发

# 克隆仓库
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 '添加神奇功能'）
  4. 推送到分支（git push origin feature/amazing-feature）
  5. 打开Pull Request

📄 许可证

MIT许可证 - 详情见LICENSE文件。

您可以：

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

🙏 致谢

📞 支持

<div align="center">

为AI开发者社区打造，充满爱心

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

Star History Chart

⬆ 返回顶部

</div>