Skip to main content
Glama
Hesccc

Linux Shell Command Executor MCP

by Hesccc
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

Linux Shell Command Executor MCP

一个基于“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 设置合理，保障系统安全。

This server cannot be installed

F
license - not found
-
quality - not tested
C
maintenance

How are these scores calculated?

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/Hesccc/shell-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server