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

多行命令（Heredoc）执行

{
  "name": "shell_exec",