MCPShell

MCPShell

MCPShell 是一款工具，可让大模型通过 Model Context Protocol (MCP) 安全地执行命令行工具。 它在大模型与操作系统命令之间提供安全桥梁。

功能

• 灵活执行命令：将任意 Shell 命令作为 MCP 工具运行， 并通过模板替换参数。
• 基于配置定义工具：使用 YAML 定义工具、参数、 限制条件和输出格式。
• 通过限制条件保障安全：执行前使用 CEL 表达式验证工具参数， 还可选择使用沙箱环境运行命令。
• 快速制作 MCP 工具原型：只需添加一些 Shell 代码，即可在大模型中将其用作 MCP 工具。
• 简单集成：适用于任何支持 MCP 协议的 LLM 客户端 （例如 Cursor、VSCode、Witsy……）

快速开始

假设你希望 Cursor（或其他 MCP 客户端）帮助你解决硬盘空间不足的问题。

1. 创建配置文件 /my/example.yaml，定义你的工具：

   mcp:
     description: |
       Tool for analyzing disk usage to help identify what's consuming space.
     run:
       shell: bash
     tools:
       - name: "disk_usage"
         description: "Check disk usage for a directory"
         params:
           directory:
             type: string
             description: "Directory to analyze"
             required: true
           max_depth:
             type: number
             description: "Maximum depth to analyze (1-3)"
             default: 2
         constraints:
           - "directory.startsWith('/')"  # Must be absolute path
           - "!directory.contains('..')"  # Prevent directory traversal
           - "max_depth >= 1 && max_depth <= 3"  # Limit recursion depth
           - "directory.matches('^[\\w\\s./\\-_]+$')"  # Only allow safe path characters, prevent command injection
         run:
           command: |
             du -h --max-depth={{ .max_depth }} {{ .directory }} | sort -hr | head -20
         output:
           prefix: |
             Disk Usage Analysis (Top 20 largest directories):
   

   查看 examples 目录，了解更多复杂且实用的示例。 也许你想通过 kubectl 让大模型了解你的 Kubernetes 集群？ 或让它运行一些 AWS CLI 命令？

2. 在 Cursor（或其他支持 MCP 的 LLM 客户端）中配置 MCP 服务

   例如，对于 Cursor，创建 .cursor/mcp.json：

   {
       // you need the "go" command available
       "mcpServers": {
           "mcp-cli-examples": {
               "command": "go",
               "args": [
                  "run", "github.com/inercia/[email protected]",
                  "mcp", "--tools", "/my/example.yaml",
                  "--logfile", "/some/path/mcpshell/example.log"
               ]
           }
       }
   }
   

   你也可以使用相对路径，并省略 .yaml 扩展名：

   {
       "mcpServers": {
           "mcp-cli-examples": {
               "command": "go",
               "args": [
                  "run", "github.com/inercia/[email protected]",
                  "mcp", "--tools", "example",
                  "--logfile", "/some/path/mcpshell/example.log"
               ]
           }
       }
   }
   

   这会在工具目录（默认为 ~/.mcpshell/tools/）中查找 example.yaml。

   查看 Cursor 或 Visual Studio Code 的配置详情。其他支持 MCP 的 LLM 也应以类似方式配置。

3. 确保刷新 MCP 客户端（Cursor 首次使用时应能自动识别，但配置文件有任何更改都需要刷新）。

4. 向大模型提问，它应该能通过新工具回答问题。例如： “我的硬盘空间快用完了。你能帮我找出问题吗？”。

使用与配置

请参阅本文档，查看所有命令。

配置文件采用 YAML 格式，定义见此处。 请参阅此目录中的示例。

如需在容器和 Kubernetes 中部署 MCPShell，请参阅容器部署指南。

Agent 模式

如需使用可将大模型直接连接到工具的 AI Agent 功能，请参阅 Don 项目。Don 提供：

• 无需单独的 MCP 客户端即可直接连接大模型
• 支持 RAG（检索增强生成）
• 多 Agent 架构
• 使用 MCPShell 的工具配置格式

安全注意事项

你可能会想： “这个 AI 帮我找到了所有那些大文件。要是我再创建一个用于删除文件的工具呢？” 千万别这么做！

• 将这些工具的范围限制为只读操作，不要赋予大模型更改内容的权限。
• 使用限制条件，将命令执行限制在安全参数范围内
• 考虑使用沙箱环境运行命令。
• 检查所有命令模板，排查潜在的注入漏洞
• 仅开放可安全供外部使用的工具
• 以上各项都要做到！

使用本软件前，请阅读安全注意事项文档。

贡献

欢迎贡献！请参阅开发指南。 请在 GitHub 上提交 Issue 或拉取请求。

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。