MCP Linux Shell Server

一个安全的模型上下文协议（MCP）服务器，提供在Linux上的Claude桌面执行Linux shell命令的能力。

特性

• 安全的Shell执行：带有适当错误处理的Linux命令执行
• 目录管理：更改和查询当前工作目录
• 符合MCP协议：完全兼容模型上下文协议
• 异步架构：采用现代的async/await模式构建
• 全面测试：经过充分测试，代码覆盖率89%

预备条件

• Python 3.8或更高版本
• Debian GNU/Linux 12 (bookworm) x86_64 或更新版本
• Claude桌面（用于集成）目前没有官方的Linux版Claude桌面应用；以下仓库可以使用但不再由创建者维护。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. 安装依赖

# 安装核心依赖
pip install -r requirements.txt

# 安装开发依赖（可选）
pip install -r requirements-dev.txt

4. 验证安装

# 运行测试以确保一切正常
python -m pytest tests/ -v --cov=linux_shell_server

Claude桌面配置

1. 查找你的Claude桌面配置

配置文件通常位于：

~/.config/claude/claude_desktop_config.json

2. 添加MCP服务器配置

在你的Claude桌面配置文件中添加以下内容：

{
  "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桌面

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

可用工具

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

工具	描述	参数
execute_command	执行shell命令	command (字符串)
change_directory	更改工作目录	path (字符串)
get_current_directory	获取当前工作目录	无

开发

运行测试

# 运行所有测试
python -m pytest tests/

# 带有覆盖率运行
python -m pytest tests/ --cov=linux_shell_server --cov-report=html

# 运行特定测试文件
python -m pytest tests/test_main.py -v

代码格式化

# 使用Black格式化代码
black linux_shell_server/ tests/

# 使用Ruff检查代码风格
ruff check linux_shell_server/ tests/

# 使用isort排序导入
isort linux_shell_server/ tests/

类型检查

mypy linux_shell_server/

安全注意事项

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

故障排除

常见问题

1. Claude桌面无法连接到MCP服务器

• 核实Claude桌面配置中的路径是否正确
• 检查虚拟环境是否已正确激活
• 确保已安装所有依赖项

2. 执行命令时出现权限错误

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

3. 模块未找到错误

• 核实Claude桌面配置中的PYTHONPATH设置是否正确
• 确保虚拟环境中包含所有必需的依赖项

调试模式

要以调试模式运行服务器进行故障排除：

# 激活虚拟环境
source yourEnv/bin/activate

# 直接运行服务器
python -m linux_shell_server.main

资源

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

许可证

本项目根据MIT许可证发布