MCP Shell 服务器

使用模型上下文协议（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"]
    }
  }
}

Cline集成

Cline是一个VS Code扩展，允许你使用MCP服务器与Claude AI一起工作。要设置此MCP shell服务器与Cline一起使用：

1. 打开你的Cline MCP设置文件：

   • macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
   • Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_m_cpc_settings.json`
   • Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

2. 添加shell服务器MCP配置：

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

   或者，如果你想使用本地安装的包：

   {
     "mcpServers": {
       "shell": {
         "command": "node",
         "args": ["/path/to/mcp-shell-server/dist/index.js"],
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

规则配置

在你的AI助手规则或提示中添加以下内容：

你有MCP Shell工具可供使用。请遵循以下关于Shell工具使用的规则：
1. 始终严格按照指定的工具调用模式，并确保提供所有必要的参数。
2. **绝不要在我面前提到工具名称。**例如，不要说“我需要使用shell_exec工具来运行这个命令”，而应该说“我会为你运行那个命令”。
3. 只在必要时使用Shell工具。如果我的任务是通用的或者你已经知道答案，就直接回应而不调用工具。
4. 当我要求你执行shell命令时，请使用适当的工具来：
   - 运行单行命令
   - 运行多行命令（当适用时使用heredoc语法）
   - 执行文件操作、git命令或系统实用程序
   - 提供相关系统信息
5. 对于可能修改系统的shell命令，务必小心，并在执行前解释该命令将做什么。
6. 如果shell命令产生错误，请用简单易懂的语言解释出了什么问题，并提出解决方法。

使用

直接执行

node dist/index.js
# 或作为可执行文件
./dist/index.js

开发模式

pnpm dev

使用MCP Inspector进行测试

pnpm inspect

命令行参数

-s, --shell <shell>  指定要使用的shell路径
-w, --working-dir <directory>  指定命令执行的工作目录
-h, --help           显示帮助信息
-V, --version        显示版本信息

工具参考

shell_exec

在指定的shell中执行命令。

参数：

• command (字符串，必需)：要执行的shell命令
• workingDir (字符串，可选)：执行命令的工作目录。必须位于$HOME下。

资源参考

服务器提供以下系统信息作为资源：

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!"
  }
}

多行命令（Heredoc）执行

{
  "name": "shell_exec",
  "parameters": {
    "command": "cat << EOF | grep 'example'\nThis is an example text.\nAnother line without the keyword.\nEOF"
  }
}

开发

项目结构

src/
├── index.ts                # 主入口点
└── shell-server/
    ├── index.ts            # Shell服务器实现
    └── lib/
        └── logger.ts       # 日志配置

日志

日志写入到mcp-shell.log文件。

许可证

MIT