Linux Shell Server

MCP Linux Shell服务器

一个安全的模型上下文协议（MCP）服务器，为Linux上的Claude Desktop提供Linux shell命令执行功能

特性

• 安全外壳执行：执行Linux命令并进行适当的错误处理
• 目录管理：更改和查询当前工作目录
• 符合MCP协议：与模型上下文协议完全兼容
• 异步架构：采用现代async/await模式构建
• 综合测试：测试良好，代码覆盖率为89%

先决条件

• Python 3.8或更高版本
• Debian GNU/Linux 12（书虫）x86_64或更高版本
• Claude Desktop（用于集成）Linux没有官方的Claude Desktop应用程序；以下存储库可以工作，但不再由创建者维护。 克劳德桌面debian

安装

1.克隆存储库

git clone https://github.com/Frost26/mcp-linux-shell-server.git
cd mcp-linux-shell-server

2.创建虚拟环境

python3 -m venv mcpEnv
source mcpEnv/bin/activate

3.安装依赖项

# Install core dependencies
pip install -r requirements.txt

# Install development dependencies (optional)
pip install -r requirements-dev.txt

4.验证安装

# Run tests to ensure everything works
python -m pytest tests/ -v --cov=linux_shell_server

Claude桌面配置

1.找到您的Claude桌面配置

配置文件通常位于：

~/.config/claude/claude_desktop_config.json

2.添加MCP服务器配置

将以下内容添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "linux-shell": {
      "command": "/path/to/your/mcp-linux-shell-server/mcpEnv/bin/python",
      "args": [
        "-m",
        "linux_shell_server.main"
      ],
      "env": {
        "PYTHONPATH": "/path/to/your/mcp-linux-shell-server"
      }
    }
  }
}

3.更新路径

替换 /path/to/your/mcp-linux-shell-server 使用您的实际项目目录路径。

本项目示例：

{
  "mcpServers": {
    "linux-shell": {
      "command": "/home/AI/Documents/CodeProjects/mcp-linux-shell-server/mcpEnv/bin/python",
      "args": [
        "-m",
        "linux_shell_server.main"
      ],
      "env": {
        "PYTHONPATH": "/home/AI/Documents/CodeProjects/mcp-linux-shell-server"
      }
    }
  }
}

4.重新启动克劳德桌面

更新配置后，重新启动Claude Desktop以加载MCP服务器。

可用工具

MCP服务器提供三个主要工具：

发展

运行测试

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=linux_shell_server --cov-report=html

# Run specific test file
python -m pytest tests/test_main.py -v

代码格式化

# Format code with Black
black linux_shell_server/ tests/

# Check code style with Ruff
ruff check linux_shell_server/ tests/

# Sort imports with isort
isort linux_shell_server/ tests/

类型检查

mypy linux_shell_server/

安全考虑

• 命令在用户运行MCP服务器的上下文中执行
• 无内置命令过滤或沙盒（谨慎使用）
• 错误输出被捕获并安全返回
• 工作目录更改与服务器进程隔离

故障排除

常见问题

1.克劳德桌面无法连接到MCP服务器

• 验证Claude Desktop配置中的路径是否正确
• 检查虚拟环境是否已正确激活
• 确保安装了所有依赖项

2.执行命令时权限错误

• MCP服务器以与用户相同的权限运行
• 确保用户对正在执行的命令具有适当的权限

3.模块未找到错误

• 验证 PYTHONPATH 在Claude Desktop配置中设置正确
• 确保虚拟环境包含所有必需的依赖关系

调试模式

要在调试模式下运行服务器进行故障排除，请执行以下操作：

# Activate virtual environment
source yourEnv/bin/activate

# Run server directly
python -m linux_shell_server.main

资源

• 模型上下文协议文档
• MCP Python SDK
• 克劳德桌面MCP指南

许可证

该项目根据麻省理工学院许可证获得许可