blazickjp_shell-mcp-server

🚀 🖥️ Shell MCP 服务器

🚀 Shell MCP 服务器专为 Model Context Protocol 构建，能为 AI 应用程序添加安全的 Shell 命令执行功能，让您的 AI 应用更加安全、高效！

🚀 快速开始

安装

# 使用 pip
pip install shell-mcp-server

# 使用 uv（推荐）
uv pip install shell-mcp-server

🔌 Claude 桌面集成

将此内容添加到您的 Claude Desktop 配置中以启用 Shell 命令执行：

{
    "mcpServers": {
        "shell-mcp-server": {
            "command": "uv",
            "args": [
                "--venv",
                ".venv",
                "python",
                "-m",
                "shell_mcp_server.server",
                "--port",
                "23456"
            ]
        }
    }
}

✨ 主要特性

• 🔒 安全执行 - 命令仅在指定目录中运行
• 🐚 多 Shell 支持 - 支持 bash、sh、cmd、powershell
• ⏱️ 超时控制 - 自动终止长时间运行的命令
• 🌍 跨平台 - 适用于 Unix 和 Windows 系统
• 🛡️ 安全为先 - 内置目录和 Shell 验证

💻 使用示例

基础用法

# 启动服务器
uv python -m shell_mcp_server.server --port 23456

# 发送命令
curl http://localhost:23456/shell -X POST -d "echo Hello World!"

高级用法

from shell_mcp_server import ShellMCPClient

client = ShellMCPClient("http://localhost:23456")
# 执行命令并获取输出
result = client.run_command("ls -a")
print(result.stdout)  # 输出结果

📚 详细文档

配置

通过以下方式配置服务器：

# 启动时指定配置文件
uv python -m shell_mcp_server.server --config config.json

config.json 示例：

{
    "port": 23456,
    "allowed_commands": ["ls", "echo"],
    "super_users": ["user1", "user2"]
}

安全特性

• 命令白名单 - 只允许指定的命令执行
• 超级用户支持 - 允许特定用户绕过命令限制
• 访问控制 - 通过 IP 或其他方式限制连接

开发

设置开发环境：

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate

# 安装开发依赖
uv pip install -e ".[test]"

# 运行测试
python -m pytest

# 带覆盖率运行测试
python -m pytest --cov=shell_mcp_server

贡献

欢迎贡献！请随意：

• 🐛 报告问题
• 💡 提建议
• 🔧 提交拉取请求
• 📚 改进文档

📄 许可证

MIT 许可证 - 详见 LICENSE 了解详细信息。