Linuxshell MCP

🚀 Linux Bash MCP 服务器

这是一个强大的模型上下文协议（MCP）服务器，可让 Claude Desktop 在 Windows 系统的任何 WSL2 Linux 发行版中执行 bash 命令和脚本。该服务器具备通用的 Linux 兼容性、智能的发行版检测功能以及全面的安全措施。

🚀 快速开始

# 1. 克隆仓库
git clone https://github.com/yourusername/linux-bash-mcp-server.git
cd linux-bash-mcp-server

# 2. 运行自动设置脚本
npm run fix

# 3. 重启 Claude Desktop
# 4. 开始在 Claude 中使用 Linux 命令！

✨ 主要特性

• 🐧 通用 Linux 支持：支持 Ubuntu、Debian、Fedora、openSUSE、Alpine 等多种 Linux 发行版。
• 🔍 智能发行版检测：自动检测并配置可用的 WSL 发行版。
• 🛡️ 安全配置合并：在设置过程中保留现有的 MCP 服务器配置。
• 🔧 全面诊断：内置故障排除和自动修复工具。
• ⚡ 高性能：优化命令执行，支持可配置的超时时间。
• 📊 详细日志记录：提供调试模式，便于故障排除和监控。
• 🔄 易于管理：提供简单的脚本用于设置、测试和维护。

🛠️ 可用工具

📋 前提条件

• 已安装 WSL2 的 Windows 系统
• WSL2 中的任意 Linux 发行版（如 Ubuntu、Debian 等）
• Node.js 18 及以上版本
• Claude Desktop 应用程序

🎯 安装与设置

选项 1：自动设置（推荐）

git clone https://github.com/yourusername/linux-bash-mcp-server.git
cd linux-bash-mcp-server
npm run fix

选项 2：手动设置

# 安装依赖
npm install

# 运行交互式设置
npm run setup

# 测试功能
npm test

选项 3：快速诊断

# 检查问题
npm run debug

# 验证配置
npm run check-config

⚙️ 配置

服务器会自动检测您的 WSL 发行版并进行自我配置。您也可以在 config.json 中进行手动配置：

{
  "wslDistribution": "auto-detect",
  "defaultTimeout": 30000,
  "scriptTimeout": 60000,
  "maxBufferSize": 10485760,
  "debugMode": false
}

🔧 可用脚本

🐧 支持的 Linux 发行版

• Ubuntu（最常用）
• Debian
• Fedora
• openSUSE
• Alpine Linux
• Kali Linux
• Oracle Linux
• 以及更多...

💻 使用示例

配置完成后，您可以在 Claude Desktop 中使用以下命令：

系统管理

• "显示我的 Linux 环境的全面系统信息"
• "检查磁盘使用情况和可用空间"
• "按 CPU 使用率列出正在运行的进程"

文件操作

• "列出 /var/log 目录下的所有文件并显示详细信息"
• "查找最近 24 小时内修改过的文件"
• "显示 /home 目录下的目录大小"

开发任务

• "检查 Docker 是否正在运行"
• "显示我家目录下仓库的 git 状态"
• "列出已安装的 Python 包"

自动化

• "为我的文档创建备份脚本"
• "生成系统监控脚本"
• "创建日志轮转脚本"

🛡️ 安全特性

• 配置保留：不会覆盖现有的 MCP 服务器配置。
• 自动备份：对损坏的配置进行备份。
• 输入验证：验证所有命令和参数。
• 超时保护：防止命令挂起。
• 错误处理：提供全面的错误报告和恢复机制。

🔍 故障排除

快速修复

npm run fix        # 自动解决常见问题
npm run debug      # 详细诊断

常见问题

未找到 WSL

wsl --install
wsl --install -d Ubuntu

缺少依赖项

npm install

配置问题

npm run check-config
npm run setup

服务器无法启动

npm run debug

详细解决方案请参阅 TROUBLESHOOTING.md。

🤝 与其他 MCP 服务器集成

该服务器可与以下服务器无缝协作：

• PowerShell MCP 服务器（Windows 命令）
• Memory MCP 服务器（持久笔记）
• File MCP 服务器（文件操作）
• Git MCP 服务器（版本控制）
• 任何其他 MCP 服务器

📚 项目结构

linux-bash-mcp-server/
├── src/
│   └── index.js              # 主 MCP 服务器
├── test/
│   └── test.js               # 全面测试
├── examples/
│   ├── system_info.sh        # 示例监控脚本
│   └── file_operations.sh    # 示例文件操作脚本
├── config.json               # 服务器配置
├── setup.js                  # 交互式设置
├── debug.js                  # 诊断工具
├── quick-fix.js             # 自动修复工具
├── check-config.js          # 配置检查器
└── README.md                # 本文件

🔄 版本历史

v1.0.0（当前版本）

• ✅ 通用 Linux 发行版支持
• ✅ 智能 WSL 发行版检测
• ✅ 安全配置合并
• ✅ 全面诊断工具
• ✅ 自动修复工具
• ✅ 增强的错误处理
• ✅ 支持调试模式

🤝 贡献

欢迎贡献代码！请按照以下步骤进行：

1. 分叉仓库
2. 创建功能分支
3. 进行更改
4. 如有必要，添加测试
5. 更新文档
6. 提交拉取请求

📄 许可证

本项目采用 MIT 许可证，请参阅 LICENSE 文件获取详细信息。

🆘 支持

• 问题反馈：GitHub Issues
• 文档：项目 Wiki
• 讨论：GitHub Discussions

🙏 致谢

• Anthropic 提供的模型上下文协议
• Microsoft 提供的 WSL2 技术
• 开源社区 提供的 Linux 发行版和工具

为 Claude Desktop 和 Linux 社区用心打造 ❤️

⭐ 如果您觉得这个仓库有用，请给它加星！