Mkusaka MCP Shell Server

🚀 MCP Shell Server 中文文檔

一個使用 Model Context Protocol (MCP) 執行 shell 命令的服務器。它作為一個橋樑，允許 AI 代理安全地執行 shell 命令。

✨ 主要特性

• 執行 shell 命令（支持單行和多行命令）
• 支持多種 shell（bash、zsh、fish、powershell、cmd 等）
• 詳細的錯誤處理和日誌記錄
• 兼容 MCP Inspector

📦 安裝指南

使用 npm 安裝（以用戶身份）

# 使用 npm
npm install -g @mkusaka/mcp-shell-server

# 使用 yarn
yarn global add @mkusaka/mcp-shell-server

# 使用 pnpm
pnpm add -g @mkusaka/mcp-shell-server

從源碼安裝（用於開發）

# 克隆倉庫
git clone https://github.com/mkusaka/mcp-shell-server.git
cd mcp-shell-server

# 安裝依賴項
pnpm install

# 構建項目
pnpm build

📚 詳細文檔

MCP 配置

Cursor 配置

在你的 Cursor 配置文件（~/.cursor/config.json）中添加以下內容：

{
  "mcpServers": {
    "shell": {
      "command": "npx",
      "args": ["-y", "@mkusaka/mcp-shell-server"]
    }
  }
}

規則配置

在你的 Cursor 規則文件中添加以下內容：

你有解決任務的工具可用。請遵循以下關於工具調用的規則：
1. **始終**按照工具調用模式完全精確地指定參數。
2. 對話中可能引用不再提供的工具。**絕不要調用未明確提供的工具**。
3. **決不要在與用戶對話時提及工具名稱**。例如，不要說“我需要使用 shell_exec 工具來執行你的命令”，而應直接說“我會執行你的命令”。
4. 只有在必要時才調用工具。如果用戶的任務是通用的或你已經知道答案，則直接響應而無需調用工具。
5. 每次調用工具之前，先向用戶解釋為什麼需要調用該工具。

使用方法

直接執行

node dist/index.js
# 或者作為可執行文件運行
./dist/index.js

開發模式

pnpm dev

使用 MCP Inspector 測試

pnpm inspect

命令行參數

-s, --shell <shell>  指定要使用的 shell 路徑
-h, --help           顯示幫助信息
-V, --version        顯示版本信息

工具引用

shell_exec

執行指定 shell 中的命令。

參數：

• command (string, 必填)：要執行的 shell 命令

資源引用

服務器提供的以下系統信息作為資源：

hostname

返回系統的主機名。

URI: hostname://

platform

返回操作系統平臺。

URI: platform://

shell

返回服務器使用的 shell 路徑。

URI: shell://

username

返回當前用戶名。

URI: username://

system-info

返回包含以下信息的綜合系統信息（JSON 格式）：

• 主機名
• 平臺
• shell
• 用戶名
• CPU 核心數
• 總內存
• 自由內存
• 系統運行時間

💻 使用示例

基本用法

{
  "name": "shell_exec",
  "parameters": {
    "command": "echo Hello, World!"
  }
}

高級用法

{
  "name": "shell_exec",
  // 這裡可以根據實際情況添加高級場景說明
}