🚀 MCP Shell Server 中文文档

MCP Shell Server 是一个借助 Model Context Protocol (MCP) 来执行 shell 命令的服务器。它充当 AI 代理与 shell 命令执行之间的桥梁，让 AI 代理能够安全地执行 shell 命令。

🚀 快速开始

MCP Shell Server 允许你通过 MCP 协议执行 shell 命令，支持多种 shell 类型，具备详细的错误处理和日志记录功能，并且与 MCP Inspector 兼容。以下是使用该服务器的基本步骤：

npx mcp-shell-server

✨ 主要特性

• 执行 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/config.json）中：

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

Cline 集成

将以下内容添加到 ~/.config/cursor/cursor.json：

{
  "shell": {
    "serverUrl": "http://localhost:13000"
  }
}

配置选项

npx mcp-shell-server --port=13000 --config=config.json

参数说明：

• --port：指定服务器监听的端口，默认为 13000。
• --config：指定配置文件路径。

系统信息查询

访问以下接口获取系统信息：

• http://localhost:13000/system-info
• http://localhost:13000/shell（返回当前使用的 shell 路径）

💻 使用示例

基础用法

基本命令执行

{
  "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 许可证。