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/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

系统信息查询

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

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

配置选项

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

参数说明：

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

示例用法

基本命令执行

{
  "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