JinDaGe - mcp-server-shell-exec MCP Details

article

README

🚀 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 命令。 | 参数 | 详情 | |------|------| | command (string, 必填) | 要执行的 shell 命令 | | runInBackground (boolean, 可选) | 是否在后台运行命令，默认值为 false | | timeoutMs (number, 可选) | 命令的超时时间（以毫秒为单位），默认值为 30000 |

返回值： | 属性 | 详情 | |------|------| | success (boolean) | 命令是否执行成功 | | output (string) | 命令执行输出的结果 |

reset-shell

重置 Shell 会话，此操作会终止当前会话并启动一个新的会话。 | 参数 | 详情 | |------|------| | 无 | |

返回值： | 属性 | 详情 | |------|------| | success (boolean) | 是否成功重置了 Shell 会话 | | message (string) | 状态信息 |

🔧 技术细节

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

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

🔍 兼容性要求

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

📄 许可证

本项目采用 MIT 许可证。

mcp-server-shell-exec