Shell Execution MCP Server

Shell 执行 MCP 服务

一个模型上下文协议（MCP）服务，为 Claude 和其他兼容 MCP 的 AI 助手提供持久的 Shell 命令执行能力。

功能

• 持久 Shell 会话：在同一会话中的不同命令之间保留状态
• 后台执行：在后台运行命令，并妥善管理进程
• 跨平台：使用相应的 Shell，可在 macOS、Linux 和 Windows 上运行
• 超时控制：配置命令执行超时时间，防止命令挂起
• 重置会话：可根据需要重置 Shell 会话

安装

# Clone the repository
git clone https://github.com/samihalawa/mcp-server-shell-exec.git
cd mcp-server-shell-exec

# Install dependencies
npm install

# Make the server executable
chmod +x server.js

用法

启动服务

npm start

配置

将服务添加到 MCP 配置中：

macOS/Linux

{
  "mcpServers": {
    "shell-exec-server": {
      "command": "/path/to/node",
      "args": [
        "/absolute/path/to/mcp-server-shell-exec/server.js"
      ]
    }
  }
}

Windows

{
  "mcpServers": {
    "shell-exec-server": {
      "command": "node",
      "args": [
        "C:\\path\\to\\mcp-server-shell-exec\\server.js"
      ]
    }
  }
}

可用工具

execute-command

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

参数：

• command（字符串，必填）：要执行的 Shell 命令
• runInBackground（布尔值，可选）：是否在后台运行命令。默认值：false
• timeoutMs（数字，可选）：命令超时时间，单位为毫秒。默认值：30000

返回值：

• success（布尔值）：命令是否执行成功
• output（字符串）：命令执行的输出

reset-shell

重置 Shell 会话。这将终止当前会话并启动一个新会话。

参数：无

返回值：

• success（布尔值）：Shell 是否重置成功
• message（字符串）：状态消息

使用示例

1. 执行简单命令：

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

2. 在后台运行长时间执行的命令：

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

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

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

4. 重置 Shell 会话：

   reset-shell()
   

工作原理

该服务使用 Node.js 创建 Shell 进程，并在不同命令之间保留状态。这样可以：

• 在不同命令之间保留环境变量
• 保持工作目录不变
• 让后台进程继续运行
• 执行需要 stdin/stdout 的交互式命令

要求

• Node.js 14+
• 兼容 Claude Desktop、Cursor 和其他兼容 MCP 的应用程序

故障排除

如果 MCP 服务遇到问题，请检查以下内容：

常见错误：工具执行失败

如果出现“工具执行失败”错误，请检查：

1. 服务是否正常运行
2. 配置文件是否使用绝对路径
3. 更改配置后是否重新启动了客户端应用程序

测试服务

可以直接发送命令来测试服务：

echo '{"id":"test1","jsonrpc":"2.0","method":"execute-command","params":{"command":"echo \"Hello World\""}}' | node server.js

这应返回格式正确的 JSON 响应，其中包含输出。

配置路径问题

仔细检查配置中的路径：

• 使用绝对路径，而非相对路径
• Windows 用户请在路径中使用正斜杠（/）或转义后的反斜杠（\）
• 确认服务文件路径正确