🖥️ Shell MCP Server

🚀 使用 Shell MCP Server 为您的AI应用程序添加安全的shell命令执行能力！构建于模型上下文协议之上。

<a href="https://glama.ai/mcp/servers/@blazickjp/shell-mcp-server"> <img width="380" height="200" src="https://gips3.baidu.com/it/u=3910246883,556949910&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Shell Server MCP 服务器" /> </a>

✨ 功能

• 🔒 安全执行 - 命令仅在指定目录中运行
• 🐚 多种shell支持 - 支持 bash, sh, cmd, powershell
• ⏱️ 超时控制 - 自动终止长时间运行的命令
• 🌍 跨平台 - 在Unix和Windows系统上均可工作
• 🛡️ 默认安全 - 内置目录和shell验证

🚀 快速开始

安装

# 使用 pip
pip install shell-mcp-server

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

🔌 Claude Desktop 集成

在您的 Claude Desktop 配置中添加以下内容以启用shell命令执行：

<details> <summary>📝 点击查看配置</summary>

{
    "mcpServers": {
        "shell-mcp-server": {
            "command": "uv",
            "args": [
                "--directory",
                "/path/to/shell-mcp-server",
                "run",
                "shell-mcp-server",
                "/path/to/allowed/dir1",
                "/path/to/allowed/dir2",
                "--shell", "bash", "/bin/bash",
                "--shell", "zsh", "/bin/zsh"
            ]
        }
    }
}

</details>

🎮 使用示例

基本文件操作

# 列出目录内容
result = execute_command(
    command="ls -la",
    shell="bash",
    cwd="/path/to/project"
)

# 按模式查找文件
result = execute_command(
    command="find . -name '*.py'",
    shell="bash",
    cwd="/path/to/project"
)

项目管理

# Git 操作
result = execute_command(
    command="git status && git diff",
    shell="bash",
    cwd="/path/to/repo"
)

# 包管理
result = execute_command(
    command="pip list --outdated",
    shell="bash",
    cwd="/path/to/python/project"
)

系统信息

# 资源使用情况
result = execute_command(
    command="df -h && free -h",
    shell="bash",
    cwd="/path/to/dir"
)

# 进程监控
result = execute_command(
    command="ps aux | grep python",
    shell="bash",
    cwd="/path/to/dir"
)

文件处理

# 搜索文件内容
result = execute_command(
    command="grep -r 'TODO' .",
    shell="bash",
    cwd="/path/to/project"
)

# 文件操作
result = execute_command(
    command="awk '{print $1}' data.csv | sort | uniq -c",
    shell="bash",
    cwd="/path/to/data"
)

Windows 特定示例

# 列出进程
result = execute_command(
    command="Get-Process | Where-Object {$_.CPU -gt 10}",
    shell="powershell",
    cwd="C:\\path\\to\\dir"
)

# 系统信息
result = execute_command(
    command="systeminfo | findstr /B /C:'OS'",
    shell="cmd",
    cwd="C:\\path\\to\\dir"
)

⚙️ 配置

通过命令行参数配置行为：

参数	描述
directories	📁 允许的目录列表
--shell name path	🐚 shell 规格（名称和路径）

环境变量：

• COMMAND_TIMEOUT: ⏱️ 最大执行时间（秒，默认：30）

🛡️ 安全特性

• 🔐 目录隔离：命令只能在指定目录中执行
• 🔒 shell 控制：只允许配置的shell
• ⏰ 超时保护：所有命令都有可配置的超时
• 🛑 路径验证：工作目录验证防止遍历攻击
• 👤 权限隔离：命令以与服务器进程相同的权限运行

🛠️ 开发

设置您的开发环境：

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

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

# 运行测试
python -m pytest

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

🤝 贡献

欢迎贡献！您可以：

• 🐛 报告错误
• 💡 提出功能建议
• 🔧 提交拉取请求
• 📚 改进文档

📜 许可证

MIT 许可证 - 详情见 LICENSE。

---

<div align="center">

🌟 用安全的shell访问增强您的AI！🌟

构建于 模型上下文协议 | 由 MCP 社区制作 ❤️

<details> <summary>🎉 在 GitHub 上给我们的项目点赞！</summary> <br> 如果您觉得这个工具很有用，请考虑给它一个星！这有助于其他人发现这个项目。 </details> </div>