Linux Administration MCP

Linux管理MCP服务器

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

概述

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

特性

🔧 核心能力

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

📊 可用工具

1. ssh_connect_test -测试SSH连接并检索基本系统信息
2. ssh_execute -在具有完整输出捕获的远程服务器上执行任何命令
3. ssh_diagnose_system -运行全面的系统诊断
4. ssh_check_service -检查特定服务的状态和日志
5. ssh_manage_service -启动、停止、重新启动、启用或禁用服务
6. ssh_analyze_logs -分析和搜索日志文件
7. ssh_network_diagnostics -运行网络诊断和连接测试
8. ssh_install_package -使用适当的包管理器安装包
9. ssh_check_security -执行安全审计
10. view_command_logs -查看所有已执行命令的审核日志
11. get_log_status -获取当前日志记录配置和统计信息

先决条件

• 启用MCP工具包的Docker桌面
• Docker MCP CLI插件(docker mcp 命令）
• SSH访问目标Linux服务器
• 用于身份验证的SSH密钥或密码

安装

步骤1：克隆存储库

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

第二步：构建Docker镜像

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

步骤3：创建自定义目录

# Create catalogs directory if it doesn't exist
mkdir -p ~/.docker/mcp/catalogs

# Create custom.yaml
cat > ~/.docker/mcp/catalogs/custom.yaml > ~/.docker/mcp/registry.yaml << 'EOF'
  linux-admin:
    ref: ""
EOF

步骤5：配置Claude桌面

查找您的Claude Desktop配置文件：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• 视窗: %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 使用您的实际用户名

步骤6：创建日志目录（可选但推荐）

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

窗户：

# Option 1: Use C:\logs
mkdir C:\logs

# Option 2: Use a user-specific directory
mkdir C:\Users\%USERNAME%\Documents\LinuxAdminLogs

macOS/Linux：

# Option 1: Use system log directory (requires sudo)
sudo mkdir -p /var/log/linux-admin
sudo chmod 755 /var/log/linux-admin

# Option 2: Use home directory
mkdir -p ~/linux-admin-logs

步骤7：重新启动克劳德桌面

1. 完全退出克劳德桌面
2. 重新启动克劳德桌面
3. Linux管理工具现在应该可用了！

身份验证方法

服务器支持多种身份验证方法，并在运行时提供凭据：

1.密码验证

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

"Connect to server.example.com with username admin and password mypassword"

2.SSH密钥认证

在工具调用中指定关键路径：

"Connect to server.example.com using key at /path/to/key"

3.默认SSH密钥

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

• 系统默认SSH密钥（~/.SSH/id_rsa、~/.SSH/id_edu25519等）
• 在SSH_key_PATH环境变量中配置的任何密钥（可选）

4.与秘密管理集成

设计用于与外部秘密管理系统配合使用。您的应用程序可以：

1. 从秘密服务器检索凭据
2. 在运行时将它们传递给Linux管理工具
3. 永远不要永久存储凭据

日志文件组织

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

• 格式: hostname-MMDDYYYY.json （例如。， webserver-01012025.json)
• 旋转：Daily-每天为每个主机创建新的日志文件
• 位置：已配置LOG_DIR目录（默认为 /tmp/linux-admin-logs)
• 内容：JSON行格式，包含所有命令执行细节

日志文件命名示例：

• 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中，您可以使用自然语言命令：

基本连接测试

"Test SSH connection to server 192.168.1.100 with username admin and password secret123"

系统诊断

"Connect to webserver.example.com as root with my SSH key at /home/user/.ssh/web_key and check if it's running properly"
"Run full diagnostics on database server at 10.0.0.5 using password authentication"

服务管理

"Check the nginx service status on production server (use admin account with password)"
"Restart MySQL on database.local using root account"
"Stop and disable Apache on web-server-01"

软件包安装

"Install htop on server1.example.com (connect as admin)"
"Install docker on ubuntu-server.local using sudo user"

安全审计

"Check for security issues on my public-facing server (use key authentication)"
"Show me failed login attempts on auth-server"
"List all users with sudo access on prod-server"

日志分析

"Find errors in the Apache logs on webserver"
"Search for 'connection refused' in system logs on db-server"
"Show me the last 100 lines of nginx error log"

网络诊断

"Test connectivity from web-server to database-server"
"Check if port 443 is open on api.example.com"
"Run traceroute from server1 to google.com"

审计跟踪审查

"Show me all commands executed on production-server"
"What commands were run yesterday on any server?"
"Show failed commands from webserver for the last week"
"Get the current log status"

建筑

Claude Desktop
      ↓
MCP Gateway (Docker)
      ↓
Linux Admin MCP Server (Container)
      ↓
    SSH (with runtime credentials)
      ↓
Remote Linux Servers
      ↓
Audit Logs (JSON) → Your Configured Directory
                     ├── server1-01152025.json
                     ├── server2-01152025.json
                     └── server3-01162025.json

安全考虑

认证

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

审计日志

• 完整路线：每个命令都会记录时间戳、用户和结果
• JSON格式：结构化日志，便于解析和分析
• 每日轮换：每个主机名自动进行每日日志轮换
• 可配置位置：选择您自己的安全日志目录
• 合规就绪：适用于法规合规要求

最佳实践

1. 尽可能使用SSH密钥而不是密码
2. 与适当的秘密管理系统集成
3. 定期轮换SSH密钥和密码
4. 定期审查审计日志
5. 使用特定的用户帐户，并不总是root
6. 对敏感服务器实施网络分段
7. 启用防火墙规则以限制SSH访问
8. 使用跳转主机访问生产服务器
9. 设置日志轮换和归档以实现长期存储

日志格式

日志以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配置具有自定义目录路径
• 完全重新启动克劳德桌面

日志记录问题

• 检查日志目录是否存在并且可写
• 验证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连接中的异步处理正确

发展

添加新工具

1. 编辑 linux_admin_server.py
2. 添加新功能 @mcp.tool() 装饰器
3. 包括用于身份验证的密码和key_path参数
4. 仅使用单行文档字符串
5. 返回带状态指示器的格式化字符串
6. 使用新工具名称更新目录
7. 重建Docker镜像

本地测试

# Run server directly with optional log directory
export LOG_DIR="/tmp/test-logs"  # Optional
python linux_admin_server.py

# Test MCP protocol
echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | python linux_admin_server.py

环境变量

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 添加新功能的测试
4. 更新文档
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件

支持

对于问题、疑问或建议：

• 在GitHub上打开一个问题
• 检查现有问题的解决方案
• 报告问题时提供详细的日志

致谢

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

更新日志

版本3.0.1（最新）

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

版本3.0.0

• 突破性变化：删除了对Docker机密的要求
• 新：现在可以在运行时提供所有SSH凭据
• 新：LOG_DIR现在是可选的，可以回退到 /tmp/linux-admin-logs
• 改进的：通过多种方法实现更好的身份验证灵活性
• 增强：专为与外部秘密管理系统集成而设计
• 固定的：服务器成功启动，没有任何必需的环境变量

版本2.0.0

• LOG_DIR需要作为环境变量
• 添加了基于主机名的日志文件组织
• 实现了每个主机名的每日日志轮换
• 添加 get_log_status 工具
• 增强 view_command_logs 带过滤功能

版本1.0.0

• 具有核心SSH管理功能的初始版本
• 固定目录的基本日志记录