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 社區用心打造 ❤️

⭐ 如果您覺得這個倉庫有用，請給它加星！