MCP Server Shell Exec

🚀 Shell 执行 MCP 服务器

这是一个提供持久 shell 命令执行功能的 Model Context Protocol (MCP) 服务器，特别适用于 Claude 以及其他支持 MCP 协议的 AI 助手，能帮助你高效地运行和管理 shell 命令。

🚀 快速开始

你可以按照以下步骤快速启动该 MCP 服务器：

# 克隆仓库
git clone https://github.com/samihalawa/mcp-server-shell-exec.git
cd mcp-server-shell-exec

# 安装依赖
npm install

# 构建服务器
npm run build

# 启动服务器
npm start

✨ 主要特性

• 持久 Shell 会话：在同一会话里，能有效保持命令间的状态，让操作更连贯。
• 后台执行：采用恰当的进程管理方式，可在后台稳定运行命令。
• 跨平台支持：无论是 macOS、Linux 还是 Windows 系统，只要搭配合适的 shell 都能使用。
• 超时控制：你可以灵活配置命令的执行超时时间，避免长时间挂起的情况。
• 会话重置：若有需求，可随时重置 Shell 会话。

📦 安装指南

克隆仓库

git clone https://github.com/samihalawa/mcp-server-shell-exec.git
cd mcp-server-shell-exec

安装依赖

npm install

构建服务器

npm run build

💻 使用示例

基础用法

启动服务器

npm start

配置服务器

将服务器添加到 MCP 配置中：

{
  "servers": {
    "shell-exec-server": {
      "command": "/path/to/node",
      "args": ["/path/to/mcp-server-shell-exec/build/index.js"],
      "enabled": true,
      "port": 3006,
      "environment": {
        "NODE_PATH": "/path/to/node_modules",
        "PATH": "/usr/local/bin:/usr/bin:/bin"
      }
    }
  }
}

高级用法

执行简单命令

execute-command(command: "ls -la")

在后台运行长时间任务

execute-command(command: "sleep 60 && echo '完成'", runInBackground: true)

使用自定义超时时间执行命令

execute-command(command: "find / -name '*.js'", timeoutMs: 60000)

重置 Shell 会话

reset-shell()

📚 详细文档

可用工具

execute-command

在持久 Shell 会话中执行 shell 命令。

返回值：

reset-shell

重置 Shell 会话，此操作会终止当前会话并启动一个新的会话。

返回值：

🔧 技术细节

服务器借助 Node.js 的 node-pty 包创建伪终端，以此来维持命令间的状态，具体表现为：

• 环境变量在不同命令之间能够持久保存。
• 当前工作目录始终保持一致。
• 后台进程可以持续稳定运行。
• 需要 stdin/stdout 交互的命令也能正常执行。

🔍 兼容性要求

• Node.js 需 14+ 版本。
• 要安装 node-pty 包。
• 该服务器与 Claude Desktop、Cursor 等支持 MCP 协议的应用程序兼容。

📄 许可证

本项目采用 MIT 许可证。