Linux管理MCP

Name: Linux管理MCP
Author: Cosmicjedi

作者：Cosmicjedi2 星标更新：2025-09-25

安装使用来源：spider==github.com

项目介绍

Linux 管理 MCP 服务器

一个基于模型上下文协议（MCP）的服务器，提供高级基于SSH的Linux服务器管理功能，包括全面的命令日志记录和审计跟踪。

概述

此MCP服务器使AI助手（如Claude）能够通过SSH连接到远程Linux服务器，诊断问题，执行命令并执行管理任务，同时维护所有操作的完整审计日志。它专为希望利用AI进行服务器管理的系统管理员设计，同时通过全面的日志记录来确保安全性和合规性。

功能

🔧 核心能力

SSH 连接管理 - 测试并建立与远程服务器的安全连接
命令执行 - 在远程服务器上运行任何命令，并捕获完整的输出
系统诊断 - 包括CPU、内存、磁盘和网络在内的综合健康检查
服务管理 - 启动、停止、重启、启用或禁用服务
日志分析 - 搜索并分析远程服务器上的日志文件
网络诊断 - 测试连通性并解决网络问题
包管理 - 使用适当的包管理器安装软件
安全审计 - 检查用户访问权限、开放端口、防火墙规则和安全配置
审计跟踪 - 完整记录所有命令，并按主机名每天轮换日志
运行时凭证 - 在运行时传递SSH凭证（无需Docker密钥）

📊 可用工具

ssh_connect_test - 测试SSH连接并获取基本系统信息
ssh_execute - 在远程服务器上执行任何命令并捕获完整的输出
ssh_diagnose_system - 运行综合系统诊断
ssh_check_service - 检查特定服务的状态和日志
ssh_manage_service - 启动、停止、重启、启用或禁用服务
ssh_analyze_logs - 分析并搜索日志文件
ssh_network_diagnostics - 运行网络诊断和连通性测试
ssh_install_package - 使用适当的包管理器安装包
ssh_check_security - 执行安全审计
view_command_logs - 查看已执行命令的审计日志
get_log_status - 获取当前日志配置和统计信息

预备条件

启用了MCP工具包的Docker Desktop
Docker MCP CLI 插件 (docker mcp 命令)
对目标Linux服务器的SSH访问权限
用于身份验证的SSH密钥或密码

安装

第一步：克隆仓库

git clone https://github.com/Cosmicjedi/linux-administration-mcp.git
cd linux-administration-mcp

第二步：构建Docker镜像

docker build -t linux-admin-mcp-server .

第三步：创建自定义目录

# 如果不存在，则创建目录
mkdir -p ~/.docker/mcp/catalogs

# 创建custom.yaml
cat > ~/.docker/mcp/catalogs/custom.yaml << 'EOF'
version: 2
name: custom
displayName: 自定义MCP服务器
registry:
  linux-admin:
    description: "具有审计日志记录的高级基于SSH的Linux服务器管理"
    title: "Linux管理"
    type: server
    dateAdded: "2025-01-01T00:00:00Z"
    image: linux-admin-mcp-server:latest
    ref: ""
    readme: ""
    toolsUrl: ""
    source: ""
    upstream: ""
    icon: ""
    tools:
      - name: ssh_connect_test
      - name: ssh_execute
      - name: ssh_diagnose_system
      - name: ssh_check_service
      - name: ssh_manage_service
      - name: ssh_analyze_logs
      - name: ssh_network_diagnostics
      - name: ssh_install_package
      - name: ssh_check_security
      - name: view_command_logs
      - name: get_log_status
    environment:
      - name: LOG_DIR
        value: "/mnt/logs"
        required: false
        description: "存储审计日志的目录（可选，默认为/tmp/linux-admin-logs）"
    volumes:
      - host: "C:\\logs:/mnt/logs"
    metadata:
      category: 监控
      tags:
        - linux
        - ssh
        - 管理
        - 监控
        - 安全
        - 审计
      license: MIT
      owner: local
EOF

第四步：更新注册表

# 编辑注册表文件以添加服务器
cat >> ~/.docker/mcp/registry.yaml << 'EOF'
  linux-admin:
    ref: ""
EOF

第五步：配置Claude Desktop

找到你的Claude Desktop配置文件：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

编辑文件以添加自定义目录：

Windows 示例：

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "C:\\Users\\YourUsername\\.docker\\mcp:/mcp",
        "-v", "C:\\logs:/mnt/logs",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

macOS/Linux 示例：

{
  "mcpServers": {
    "mcp-toolkit-gateway": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v", "/var/run/docker.sock:/var/run/docker.sock",
        "-v", "/Users/YourUsername/.docker/mcp:/mcp",
        "-v", "/var/log/linux-admin:/mnt/logs",
        "docker/mcp-gateway",
        "--catalog=/mcp/catalogs/docker-mcp.yaml",
        "--catalog=/mcp/catalogs/custom.yaml",
        "--config=/mcp/config.yaml",
        "--registry=/mcp/registry.yaml",
        "--tools-config=/mcp/tools.yaml",
        "--transport=stdio"
      ]
    }
  }
}

配置说明：

卷挂载 -v YOUR_HOST_PATH:/mnt/logs 是可选但推荐的持久日志
如果未指定日志目录，日志将存储在容器内的 /tmp/linux-admin-logs
将 YourUsername 替换为您的实际用户名

第六步：创建您的日志目录（可选但推荐）

选择并创建您首选的日志目录：

Windows：

# 选项1：使用C:\logs
mkdir C:\logs

# 选项2：使用用户特定目录
mkdir C:\Users\%USERNAME%\Documents\LinuxAdminLogs

macOS/Linux：

# 选项1：使用系统日志目录（需要sudo）
sudo mkdir -p /var/log/linux-admin
sudo chmod  755 /var/log/linux-admin

# 选项2：使用家目录
mkdir -p ~/linux-admin-logs

第七步：重新启动Claude Desktop

完全退出Claude Desktop
再次启动Claude Desktop
现在应该可以使用Linux管理工具了！

认证方法

该服务器支持多种认证方法，凭据在运行时提供：

1. 密码认证

直接在工具调用中传递密码：

"使用用户名admin和密码mypassword连接到server.example.com"

2. SSH密钥认证

在工具调用中指定密钥路径：

"使用位于/path/to/key的密钥连接到server.example.com"

3. 默认SSH密钥

如果没有提供凭据，服务器将尝试使用：

系统默认SSH密钥（~/.ssh/id_rsa, ~/.ssh/id_ed25519等）
SSH_KEY_PATH环境变量中配置的任何密钥（可选）

4. 与密钥管理系统集成

设计为与外部密钥管理系统集成。您的应用程序可以：

从密钥服务器检索凭据
在运行时将其传递给Linux管理工具
永不永久存储凭据

日志文件组织

MCP服务器按照以下结构组织日志：

格式：hostname-MMDDYYYY.json（例如，webserver-01012025.json）
轮换：每日 - 每天为每个主机创建新的日志文件
位置：配置的LOG_DIR目录（默认为 /tmp/linux-admin-logs）
内容：包含所有命令执行详细信息的JSON Lines格式

日志文件命名示例：

production-server-01152025.json - 2025年1月15日在生产服务器上运行的命令
database_local-01152025.json - 2025年1月15日在database.local上运行的命令
192_168_1_100-01152025.json - 2025年1月15日在IP 192.168.1.100上运行的命令

注意：主机名中的特殊字符被替换为下划线以兼容文件系统。

使用示例

在Claude Desktop中，您可以使用自然语言命令：

基本连接测试

"测试到服务器192.168.1.100的SSH连接，用户名为admin，密码为secret123"

系统诊断

"作为root使用我的SSH密钥（位于/home/user/.ssh/web_key）连接到webserver.example.com并检查其是否正常运行"
"使用密码认证对10.0.0.5上的数据库服务器进行全面诊断"

服务管理

"检查生产服务器上的nginx服务状态（使用admin账户和密码）"
"使用root账户重启database.local上的MySQL"
"停止并禁用web-server-01上的Apache"

包安装

"在server1.example.com上安装htop（以admin身份连接）"
"使用sudo用户在ubuntu-server.local上安装docker"

安全审计

"检查我面向公众的服务器上的安全问题（使用密钥认证）"
"显示auth-server上的失败登录尝试"
"列出prod-server上具有sudo访问权限的所有用户"

日志分析

"查找webserver上的Apache日志中的错误"
"在db-server上的系统日志中搜索'connection refused'"
"显示nginx错误日志的最后100行"

网络诊断

"测试从web-server到database-server的连通性"
"检查api.example.com上的端口443是否打开"
"从server1到google.com运行traceroute"

审计跟踪审查

"显示在生产服务器上执行的所有命令"
"昨天在任何服务器上运行了哪些命令？"
"显示webserver在过去一周内失败的命令"
"获取当前日志状态"

架构

Claude Desktop
      ↓
MCP网关（Docker）
      ↓
Linux管理MCP服务器（容器）
      ↓
    SSH（带运行时凭证）
      ↓
远程Linux服务器
      ↓
审计日志（JSON）→ 您配置的目录
                     ├── server1-01152025.json
                     ├── server2-01152025.json
                     └── server3-01162025.json

安全考虑

认证

无硬编码凭据：服务器从不存储凭据
仅运行时：凭据在工具调用时传递
多种方法：支持密码、SSH密钥和系统默认值
密钥管理系统就绪：设计为与外部密钥服务器集成

审计日志

完整跟踪：每个命令都带有时间戳、用户和结果的日志
JSON格式：结构化日志易于解析和分析
每日轮换：根据主机名自动每日轮换日志
可配置位置：选择自己的安全日志目录
合规准备：适合监管合规要求

最佳实践

尽可能使用SSH密钥而不是密码
与合适的密钥管理系统集成
定期轮换SSH密钥和密码
定期审查审计日志
使用特定用户账户，而不是总是root
实现敏感服务器的网络分段
启用防火墙规则以限制SSH访问
使用跳板主机访问生产服务器
设置日志轮换和归档以实现长期存储

日志格式

日志存储在JSON Lines格式中（每行一个JSON对象）：

{
  "timestamp": "2025-01-15T12:00:00Z",
  "hostname": "server.example.com",
  "user": "admin",
  "command": "systemctl restart nginx",
  "output": "...",
  "error": "",
  "success": true
}

故障排除

SSH连接问题

验证目标服务器上的SSH服务是否正在运行
检查防火墙是否允许SSH端口（通常是22）
确认正确的主机名/IP和凭据
先手动测试SSH连接
检查服务器是否启用了密码认证

工具未出现在Claude中

验证Docker镜像是否成功构建：docker images
检查目录文件语法：cat ~/.docker/mcp/catalogs/custom.yaml
确保Claude Desktop配置中有自定义目录路径
完全重新启动Claude Desktop

日志问题

检查日志目录是否存在且可写
验证Docker配置中的卷挂载
确保有足够的磁盘空间存储日志
查看Docker容器日志：docker logs [container_id]
使用get_log_status工具检查配置

权限被拒绝错误

验证用户在目标服务器上有sudo权限
检查SSH密钥权限（应为600）
确保服务管理命令以root或sudo身份运行
检查主机系统上的日志目录权限

异步/等待错误

如果看到object NoneType can't be used in 'await' expression，请重建Docker镜像
这是一个已知问题，在版本3.0.1中修复
修复确保了SSH连接中的正确异步处理

开发

添加新工具

编辑linux_admin_server.py
添加带有@mcp.tool()装饰器的新函数
包含用于认证的密码和key_path参数
仅使用单行文档字符串
返回带有状态指示符的格式化字符串
更新目录以包含新工具名称
重新构建Docker镜像

本地测试

# 直接运行服务器，可选日志目录
export LOG_DIR="/tmp/test-logs"  # 可选
python linux_admin_server.py

# 测试MCP协议
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python linux_admin_server.py

环境变量

变量	必需	默认值	描述
`LOG_DIR`	否	`/tmp/linux-admin-logs`	存储审计日志的目录路径
`SSH_KEY_PATH`	否	无	可选默认SSH私钥路径
`SSH_KNOWN_HOSTS`	否	无	可选已知主机文件路径
`SSH_CONFIG_PATH`	否	无	可选SSH配置文件路径

贡献

欢迎贡献！请：

分叉仓库
创建功能分支
为新功能添加测试
更新文档
提交拉取请求

许可证

MIT许可证 - 详情见LICENSE文件

支持

对于问题、疑问或建议：

在GitHub上打开问题
查看现有问题以寻找解决方案
报告问题时提供详细的日志

致谢

为MCP（模型上下文协议）生态系统构建
设计用于与Claude Desktop一起使用
使用asyncssh进行安全的SSH连接
受DevOps自动化需求启发

更改日志

版本3.0.1（最新）

修复：SSH连接建立中的异步/等待问题
修复：正确处理asyncssh连接生命周期
改进：更好的异步操作错误处理

版本3.0.0

重大变更：移除了对Docker密钥的要求
新增：现在可以在运行时提供所有SSH凭据
新增：LOG_DIR现在是可选的，有默认值 /tmp/linux-admin-logs
改进：通过多种方法提高了更好的认证灵活性
增强：设计为与外部密钥管理系统集成
修复：没有必需的环境变量时服务器可以成功启动