MCP壳程序

Name: MCP壳程序
Author: sonirico

作者：sonirico45 星标更新：2025-09-17

安装使用来源：spider==github.com

项目介绍

mcp-shell 🐚

一个强大的模型上下文协议（MCP）服务器，提供安全的shell命令执行能力给AI助手和其他MCP客户端。换句话说：大脑思考，这个工具执行命令。

🧠💥🖥️ 将mcp-shell视为您的大语言模型的命令行执行器。 当语言模型在推理世界时，mcp-shell就是让它们接触现实的东西。

这是什么？

此工具通过标准化的MCP协议，在AI系统与您的shell环境之间建立桥梁。它将系统shell暴露为一个结构化的工具，支持自主工作流、工具辅助推理和解决实际问题。

基于官方的Go语言MCP SDK构建：mark3labs/mcp-go。

用Go编写，直接集成mcp-go，提供从想法到执行的清晰路径。我知道存在类似的项目——这个是我的。它以我想要的方式解决问题：最小化、可组合、可审计。

开箱即用，它通过Docker运行隔离，但这只是一个开始。路线图包括对可选监禁机制的支持，如chroot、命名空间和系统调用级别的限制——无需依赖Docker做一切。

特性

🔒 安全第一：可配置的命令白名单、黑名单和执行约束
🐳 Docker就绪：轻量级Alpine基础容器用于安全隔离
📊 结构化响应：JSON格式输出，包含标准输出、标准错误、退出码和执行元数据
🔄 二进制数据支持：可选的Base64编码处理二进制命令输出
⚡ 性能监控：执行时间跟踪和资源限制
📋 审计日志：完整的命令执行审计轨迹，带有结构化日志
🎯 上下文感知：支持具有适当上下文取消的命令执行
⚙️ 环境配置：完全通过环境变量进行配置

安全特性

命令验证：使用正则表达式模式匹配的白名单/黑名单
执行限制：可配置的超时和输出大小限制
用户隔离：以无特权用户身份运行命令
工作目录：限制执行特定目录
审计轨迹：记录所有命令执行的完整日志
资源限制：内存和CPU使用限制

快速入门

先决条件

Go 1.23或更高版本
类Unix系统（Linux、macOS、WSL）
Docker（可选，用于容器化部署）

安装

git clone https://github.com/sonirico/mcp-shell
cd mcp-shell
make install

基本用法

# 使用默认配置运行（如果全局安装）
mcp-shell

# 或者本地运行
make run

# 启用安全运行（创建临时配置）
make run-secure

# 使用自定义配置文件运行
MCP_SHELL_SEC_CONFIG_FILE=security.json mcp-shell

# 使用环境变量覆盖运行
MCP_SHELL_LOG_LEVEL=debug mcp-shell

Docker部署（推荐）

# 构建Docker镜像
make docker-build

# 在安全容器中运行
make docker-run-secure

# 为调试运行带shell访问权限
make docker-shell

配置

环境变量

通过环境变量进行基本服务和日志配置：

服务配置

MCP_SHELL_SERVER_NAME：服务器名称（默认："mcp-shell 🐚"）
MCP_SHELL_VERSION：服务器版本（编译时设置）

日志配置

MCP_SHELL_LOG_LEVEL：日志级别（debug、info、warn、error、fatal）
MCP_S_HELL_LOG_FORMAT：日志格式（json、console）
MCP_SHELL_LOG_OUTPUT：日志输出（stdout、stderr、file）

配置文件

MCP_SHELL_SEC_CONFIG_FILE：YAML配置文件路径

安全配置（仅限YAML）

安全设置仅通过YAML配置文件进行配置：

export MCP_SHELL_SEC_CONFIG_FILE=security.yaml

示例安全配置文件：

security:
  enabled: true
  allowed_commands:
    - ls
    - cat
    - grep
    - find
    - echo
  blocked_commands:
    - rm -rf
    - sudo
    - chmod
  blocked_patterns:
    - 'rm\s+.*-rf.*'
    - 'sudo\s+.*'
  max_execution_time: 30s
  working_directory: /tmp/mcp-workspace
  max_output_size: 1048576
  audit_log: true

工具参数

command（字符串，必需）：要执行的shell命令
base64（布尔值，可选）：返回标准输出/标准错误作为Base64编码的字符串

响应格式

{
  "status": "success|error",
  "exit_code": 0,
  "stdout": "命令输出",
  "stderr": "错误输出",
  "command": "执行的命令",
  "execution_time": "100ms",
  "security_info": {
    "security_enabled": true,
    "working_dir": "/tmp/mcp-workspace",
    "timeout_applied": true
  }
}

集成示例

与Claude Desktop集成

{
  "mcpServers": {
    "shell": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "mcp-shell:latest"],
      "env": {
        "MCP_SHELL_SECURITY_ENABLED": "true",
        "MCP_SHELL_LOG_LEVEL": "info"
      }
    }
  }
}

生产部署

# 构建并安装
make build
sudo make install-bin

# 设置环境变量进行基本配置
export MCP_SHELL_LOG_LEVEL=info
export MCP_SHELL_LOG_FORMAT=json
export MCP_SHELL_SEC_CONFIG_FILE=/etc/mcp-shell/config.json

# 安全配置仅在JSON文件中进行
# 运行服务
mcp-shell

开发

# 安装依赖和开发工具
make install dev-tools

# 格式化代码
make fmt

# 运行测试
make test

# 运行linter
make lint

# 为发布构建
make release

# 生成配置示例
make config-example

安全注意事项

⚠️ 重要安全提示

默认模式：当禁用安全时，以完全系统访问模式运行（当然，这是一个糟糕的想法——除非您喜欢那样）。
容器隔离：使用Docker部署增加额外的安全层
用户权限：生产环境中以非root用户身份运行
网络访问：除非明确限制，否则命令可以访问网络
文件系统：根据用户权限读写文件

贡献

分叉仓库
创建功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m '添加惊人的功能'）
推送到分支（git push origin feature/amazing-feature）
打开Pull Request

确保代码已格式化（make fmt）并通过测试（make test）。

许可证

MIT许可证 - 查看LICENSE文件获取详情。