# Linux Shell Command Executor MCP

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

---

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

### 🔧 功能概述

本项目实现了一个基于 [FastMCP](https://github.com/fastmcp/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**](https://github.com/astral-sh/uv) 替代 pip，速度快且依赖解析更高效。

#### 步骤一：克隆仓库

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

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

```bash
# 安装 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` 将其注册为系统服务。

#### 创建服务文件

```bash
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`：根据需要配置允许的命令

#### 启动并启用服务

```bash
# 重载 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 协议的客户端进行调用。

#### 示例：列出允许的命令

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

输出示例：

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

#### 示例：执行一个 shell 命令

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

成功响应示例：

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

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

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

#### 示例：查看所有可用函数

```bash
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` 设置合理，保障系统安全。