MCP Shell Server

一个使用模型上下文协议 (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 (字符串, 必需): 要执行的 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!"
  }
}

多行命令 (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