<div align="center">

command-executor MCP 服务器

<img src="https://raw.githubusercontent.com/Sunwood-ai-labs/command-executor-mcp-server/refs/heads/master/assets/header.svg" alt="命令执行器 MCP 服务器"/>

<a href="README.md"><img src="https://img.shields.io/badge/english-document-white.svg" alt="英文文档"></a> <a href="README.ja.md"><img src="https://img.shields.io/badge/ドキュメント-日本語-white.svg" alt="日文文档"/></a>

</div>

一个用于安全执行预批准命令的模型上下文协议服务器。

🎥 演示

https://github.com/user-attachments/assets/ed763a12-b685-4e0b-b9a5-bc948a590f51

✨ 特性

• 使用预批准命令列表进行安全命令执行
• 通过环境变量配置允许的命令
• 使用 TypeScript 和 MCP SDK 构建
• 通过 stdio 进行通信以实现无缝集成
• 错误处理和安全验证
• 实时命令输出流

🚀 安装

安装依赖项：

npm install

构建服务器：

npm run build

开发模式下自动重建：

npm run watch

⚙️ 配置

🔒 允许的命令

默认情况下，以下命令是允许的：

• git
• ls
• mkdir
• cd
• npm
• npx
• python

您可以通过设置 ALLOWED_COMMANDS 环境变量来自定义允许的命令：

export ALLOWED_COMMANDS=git,ls,mkdir,python

🔌 与 Claude Desktop 的集成

要与 Claude Desktop 一起使用，请添加服务器配置：

在 MacOS 上：

~/Library/Application Support/Claude/claude_desktop_config.json

在 Windows 上：

%APPDATA%/Claude/claude_desktop_config.json

配置示例：

{
  "mcpServers": {
    "command-executor": {
      "command": "/path/to/command-executor/build/index.js"
    }
  }
}

🛡️ 安全注意事项

命令执行器服务器实现了多项安全措施：

1. 预批准命令列表

   • 只有明确允许的命令可以被执行
   • 默认列表严格且注重安全性
   • 命令通过前缀验证以防止注入

2. 命令验证

   • 命令前缀验证防止命令注入
   • 不执行 shell 提高安全性
   • 环境变量被正确清理

3. 错误处理

   • 对未经授权的命令进行全面错误处理
   • 明确的错误消息便于调试
   • 失败的命令不会使服务器崩溃

4. 环境隔离

   • 服务器在其自己的环境中运行
   • 可以控制环境变量
   • 有限的系统访问权限

💻 开发

📁 项目结构

command-executor/
├─ src/
│  └─ index.ts      # 主服务器实现
├─ build/
│  └─ index.js      # 编译后的 JavaScript
├─ assets/
│  └─ header.svg    # 项目头部图像
└─ package.json     # 项目配置

🐛 调试

由于 MCP 服务器通过 stdio 进行通信，调试可能会很困难。我们推荐使用 MCP Inspector：

npm run inspector

Inspector 将提供一个 URL，以便在浏览器中访问调试工具。

🛠️ 工具 API

服务器提供了一个工具：

execute_command

执行预批准的命令。

参数：

• command (字符串，必需)：要执行的命令

请求示例：

{
  "name": "execute_command",
  "arguments": {
    "command": "git status"
  }
}

响应示例：

{
  "content": [
    {
      "type": "text",
      "text": "On branch main\nNothing to commit, working tree clean"
    }
  ]
}

错误响应示例：

{
  1. "content": [
    {
      "type": "text",
      "text": "命令执行失败：未授权的命令"
    }
  ],
  "isError": true
}

❌ 错误处理

服务器提供了各种情况下的详细错误消息：

1. 未经授权的命令

   {
     "code": "InvalidParams",
     "message": "未授权的命令：[command]。允许的命令：git, ls, mkdir, cd, npm, npx, python"
   }
   

2. 执行失败

   {
     "content": [
       {
         "type": "text",
         "text": "命令执行失败：[错误信息]"
       }
     ],
     "isError": true
   }
   

🤝 贡献

1. 分叉仓库
2. 创建您的功能分支
3. 提交更改
4. 推送到分支
5. 创建一个新的拉取请求

📄 许可证

本项目采用 MIT 许可证 - 详情见 LICENSE 文件。