MCP Server Shell Exec

🚀 Shell 執行 MCP 服務器

本項目是一個提供持久 shell 命令執行功能的 Model Context Protocol (MCP) 服務器，適用於 Claude 和其他與 MCP 兼容的 AI 助手，能在不同操作系統上為用戶提供穩定、高效的 shell 命令執行服務。

🚀 快速開始

若要使用本服務器，可按以下步驟操作：

# 克隆倉庫
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 命令。

返回：

• success (boolean)：命令是否執行成功
• output (string)：命令執行輸出的結果

reset-shell

重置 Shell 會話。此操作將終止當前會話並啟動一個新的會話。

返回：

• success (boolean)：是否成功重置了 Shell 會話
• message (string)：狀態信息

🔧 技術細節

服務器使用 Node.js 的 node-pty 包創建一個偽終端，以保持命令之間的狀態。這使得：

• 環境變量在命令之間持久
• 當前工作目錄保持一致
• 後臺進程可以繼續運行
• 需要 stdin/stdout 交互的命令能夠正常運行

📄 許可證

本項目採用 MIT 許可證。