Linux Shell Command Executor

一个基于“FastMCP”构建的极简且安全的“MCP（模型控制协议）”服务器，能够在 Linux 系统上实现对 shell 命令的受控执行。该工具使人工智能模型能够安全地与主机系统交互，通过将命令执行限制在预定义的白名单内来实现这一目的。

---

📌 1. 功能说明与实现原理

🔧 功能概述

本项目实现了一个基于 FastMCP 框架的轻量级 MCP 服务，主要功能如下：

• ✅ 安全执行 Shell 命令：允许远程调用指定的系统命令（如 ls, ps, df 等），并返回执行结果。
• 🔐 命令白名单机制：仅允许环境变量中定义的命令被执行，防止任意命令注入。
• 🛠️ 内置工具查询接口：
  • list_allowed_commands：列出所有允许执行的命令。
  • list_all_functions：列出当前 MCP 服务器支持的所有工具函数。
• ⏱️ 超时控制：每个命令执行默认设置 30 秒超时，避免长时间阻塞。
• 🚫 输入解析防护：使用 shlex.split 安全解析命令行，防止路径遍历和注入攻击。

⚙️ 实现原理

• 使用 asyncio 和 subprocess 异步执行 shell 命令，提升并发性能。
• 通过 os.getenv("ALLOWED_COMMANDS") 读取允许执行的命令列表（以逗号分隔）。
• 所有命令在执行前会提取其基础名称（basename），并与白名单比对，确保只有授权命令可运行。
• 错误处理完善，包含命令格式错误、解析失败、执行异常、超时等多种情况反馈。
• 利用 FastMCP 框架快速暴露工具函数为 MCP 协议接口，便于集成到 AI Agent 系统中。

---

🛠️ 2. 部署与配置方法

📦 推荐安装方式（使用 uv）

🌟 推荐使用 uv 替代 pip，速度快且依赖解析更高效。

步骤一：克隆仓库

git clone https://github.com/your-username/linux-shell-mcp.git
cd linux-shell-mcp

步骤二：使用 uv 创建虚拟环境并安装依赖

# 安装 uv（如未安装）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 初始化项目环境
uv venv
source .venv/bin/activate

# 安装 fastmcp（或其他所需包）
uv pip install fastmcp

💡 提示：你也可以将依赖写入 requirements.txt 并用 uv pip install -r requirements.txt 批量安装。

---

🔄 后台运行（推荐使用 systemctl）

为了长期稳定运行 MCP 服务，建议使用 systemctl 将其注册为系统服务。

创建服务文件

sudo tee /etc/systemd/system/mcp-shell.service <<EOF
[Unit]
Description=Linux Shell Command Executor MCP Server
After=network.target

[Service]
Type=simple
User=your-username
WorkingDirectory=/path/to/linux-shell-mcp
Environment="ALLOWED_COMMANDS=ls,ps,df,diskutil,ping,whoami,uname"
ExecStart=/path/to/linux-shell-mcp/.venv/bin/python /path/to/linux-shell-mcp/main.py
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

🔁 请替换以下字段：

1. your-username：实际运行用户
2. /path/to/linux-shell-mcp：项目实际路径
3. ALLOWED_COMMANDS：根据需要配置允许的命令

启动并启用服务

# 重载 systemd 配置
sudo systemctl daemon-reexec

# 启动服务
sudo systemctl start mcp-shell

# 设置开机自启
sudo systemctl enable mcp-shell

# 查看状态
sudo systemctl status mcp-shell

---

🧪 3. 使用方法

🌐 服务启动后

默认监听地址：http://0.0.0.0:8000

可通过 curl 或任何支持 MCP 协议的客户端进行调用。

示例：列出允许的命令

curl -X POST http://localhost:8000/list_allowed_commands

输出示例：

{
  "allowed_commands": ["df", "ls", "ps"],
  "count": 3,
  "description": "These are the only commands that can be executed via execute_shell_command."
}

示例：执行一个 shell 命令

curl -X POST http://localhost:8000/execute_shell_command \
     -H "Content-Type: application/json" \
     -d '{"command": "ls -l /tmp", "timeout": 10}'

成功响应示例：

{
  "command": "ls -l /tmp",
  "exit_code": 0,
  "stdout": "total 0\ndrwxr-xr-x 2 root root 4096 Apr  5 10:00 example",
  "stderr": ""
}

错误示例（命令不在白名单）：

{
  "error": "Command 'rm' is not in the allowed list",
  "allowed_commands": ["ls", "ps", "df"],
  "provided_command": "rm -rf /tmp/test"
}

示例：查看所有可用函数

curl -X POST http://localhost:8000/list_all_functions

---

🔐 安全建议

• ❗ 永远不要将危险命令（如 rm, chmod, systemctl, sh）加入白名单，除非有严格上下文控制。
• 🔐 推荐以低权限用户运行该服务，避免提权风险。
• 🔒 可结合反向代理（如 Nginx）+ HTTPS + 身份验证增强安全性。
• 📊 建议记录日志以便审计命令执行行为。

---

🤝 贡献与反馈

欢迎提交 Issue 或 Pull Request！
本项目适用于需要让 AI 安全访问系统信息的场景，如监控、诊断、自动化运维等。

---

✅ 备注：请将 your-username 和 /path/to/linux-shell-mcp 替换为实际值，并确保 ALLOWED_COMMANDS 设置合理，保障系统安全。