MCP Shell Server

一个使用模型上下文协议（MCP）执行shell命令的服务器。它作为一个桥梁，允许AI代理安全地执行shell命令。

功能

• 执行shell命令（支持单行和多行）
• 支持多种shell（bash、zsh、fish、powershell、cmd等）
• 详细的错误处理和日志记录
• 兼容MCP Inspector

安装

从npm安装（作为用户）

# Using npm
npm install -g @mkusaka/mcp-shell-server

# Using yarn
yarn global add @mkusaka/mcp-shell-server

# Using pnpm
pnpm add -g @mkusaka/mcp-shell-server

从源码安装（用于开发）

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

# Install dependencies
pnpm install

# Build the project
pnpm build

MCP配置

Cursor配置

将以下内容添加到您的Cursor配置文件(~/.cursor/config.json)中：

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

Cline集成

Cline 是一个VS Code扩展，允许您与Claude AI一起使用MCP服务器。要通过Cline设置此MCP shell服务器，请按如下步骤操作：

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_mcp_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助手的规则或提示中：

You have MCP Shell tools at your disposal. Follow these rules regarding Shell tool usage:
1. ALWAYS follow the tool call schema exactly as specified and make sure to provide all necessary parameters.
2. **NEVER refer to tool names when speaking to me.** For example, instead of saying 'I need to use the shell_exec tool to run this command', just say 'I'll run that command for you'.
3. Only use Shell tools when they are necessary. If my task is general or you already know the answer, just respond without calling tools.
4. When I ask you to execute shell commands, use the appropriate tool to:
   - Run single-line commands
   - Run multi-line commands (using heredoc syntax when appropriate)
   - Execute file operations, git commands, or system utilities
   - Provide system information when relevant
5. Always be careful with shell commands that might modify the system, and explain what the command will do before executing it.
6. If a shell command produces an error, explain what went wrong in simple terms and suggest ways to fix it.

使用

直接执行

node dist/index.js
# or as an executable
./dist/index.js

开发模式

pnpm dev

使用MCP Inspector测试

pnpm inspect

命令行参数

-s, --shell <shell>  Specify the path to the shell to use
-w, --working-dir <directory>  Specify the working directory for command execution
-h, --help           Display help message
-V, --version        Display version information

工具参考

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                # Main entry point
└── shell-server/
    ├── index.ts            # Shell server implementation
    └── lib/
        └── logger.ts       # Logging configuration

日志

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

许可证

MIT