linux-mcp-server-administration

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Linux MCP Server Administration

Linux MCP 服务器管理

Skill by ara.so — MCP Skills collection.

由ara.so提供的技能 — MCP技能集合。

Overview

概述

The Linux MCP Server is a Model Context Protocol server that provides read-only diagnostic and troubleshooting capabilities for RHEL-based Linux systems. It enables LLM clients to execute diagnostic commands on local or remote systems via SSH, making it ideal for system administration, monitoring, and troubleshooting tasks.

Key Features:

Strictly read-only operations for safe diagnostics
Remote SSH execution with key-based authentication
Multi-host management in a single session
Comprehensive system diagnostics (services, processes, logs, network, storage)
RHEL/systemd optimized

Linux MCP Server是一款Model Context Protocol服务器，为基于RHEL的Linux系统提供只读诊断和故障排查功能。它允许LLM客户端通过SSH在本地或远程系统上执行诊断命令，非常适合系统管理、监控和故障排查任务。

核心特性：

严格的只读操作，确保诊断安全
基于密钥认证的远程SSH执行
单会话多主机管理
全面的系统诊断（服务、进程、日志、网络、存储）
针对RHEL/systemd优化

Installation

安装

Using pip

使用pip

bash

pip install linux-mcp-server

bash

pip install linux-mcp-server

Using uv (recommended)

使用uv（推荐）

bash

undefined

bash

undefined

Install uv first

先安装uv

pip install uv

Install the server

安装服务器

uv pip install linux-mcp-server

undefined

uv pip install linux-mcp-server

undefined

From source

从源码安装

bash

git clone https://github.com/rhel-lightspeed/linux-mcp-server.git
cd linux-mcp-server
pip install -e .

bash

git clone https://github.com/rhel-lightspeed/linux-mcp-server.git
cd linux-mcp-server
pip install -e .

Configuration

配置

MCP Client Configuration

MCP客户端配置

Add to your MCP client settings (e.g., Claude Desktop

config.json

json

{
  "mcpServers": {
    "linux": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/linux-mcp-server",
        "run",
        "linux-mcp-server"
      ],
      "env": {
        "LINUX_MCP_ALLOWED_LOGS": "/var/log/messages,/var/log/secure,/var/log/audit/audit.log"
      }
    }
  }
}

添加到你的MCP客户端设置中（例如Claude Desktop的

config.json

）：

json

{
  "mcpServers": {
    "linux": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/linux-mcp-server",
        "run",
        "linux-mcp-server"
      ],
      "env": {
        "LINUX_MCP_ALLOWED_LOGS": "/var/log/messages,/var/log/secure,/var/log/audit/audit.log"
      }
    }
  }
}

Environment Variables

环境变量

```
LINUX_MCP_ALLOWED_LOGS
```
: Comma-separated list of log files that can be accessed (default: common system logs)
```
SSH_AUTH_SOCK
```
: SSH agent socket for key-based authentication
```
HOME
```
: User home directory (for SSH key location)

```
LINUX_MCP_ALLOWED_LOGS
```
: 可访问的日志文件列表，以逗号分隔（默认：常见系统日志）
```
SSH_AUTH_SOCK
```
: 用于密钥认证的SSH代理套接字
```
HOME
```
: 用户主目录（用于SSH密钥位置）

SSH Setup for Remote Hosts

远程主机SSH配置

Ensure SSH key-based authentication is configured:

bash

undefined

确保已配置基于密钥的SSH认证：

bash

undefined

Generate SSH key if needed

如有需要，生成SSH密钥

ssh-keygen -t ed25519 -C "your_email@example.com"

Copy public key to remote host

将公钥复制到远程主机

ssh-copy-id user@remote-host

Test connection

测试连接

ssh user@remote-host

undefined

ssh user@remote-host

undefined

Available Tools

可用工具

System Information

系统信息

get_system_info - Retrieve basic system information (hostname, OS, kernel, uptime)

python

undefined

get_system_info - 获取基础系统信息（主机名、操作系统、内核、运行时间）

python

undefined

Usage in MCP client

在MCP客户端中的用法

Ask: "What's the system info for server01?"

提问："server01的系统信息是什么？"

Tool call: get_system_info(host="user@server01")

工具调用：get_system_info(host="user@server01")


**get_uname** - Get detailed kernel and system information

```python


**get_uname** - 获取详细的内核和系统信息

```python

Usage: "Show me kernel details"

用法："展示内核详情"

Tool call: get_uname(host=None) # Local system

工具调用：get_uname(host=None) # 本地系统

undefined

undefined

Service Management

服务管理

list_services - List systemd services and their states

python

undefined

list_services - 列出systemd服务及其状态

python

undefined

Usage: "List all services on the production server"

用法："列出生产服务器上的所有服务"

Tool call: list_services(host="admin@prod-server", state="all")

工具调用：list_services(host="admin@prod-server", state="all")

States: "all", "running", "failed", "enabled", "disabled"

状态选项："all", "running", "failed", "enabled", "disabled"


**get_service_status** - Get detailed status of a specific service

```python


**get_service_status** - 获取特定服务的详细状态

```python

Usage: "Check nginx status on web01"

用法："检查web01上的nginx状态"

Tool call: get_service_status(service_name="nginx", host="root@web01")

工具调用：get_service_status(service_name="nginx", host="root@web01")

undefined

undefined

Process Management

进程管理

list_processes - List running processes

python

undefined

list_processes - 列出运行中的进程

python

undefined

Usage: "Show all processes"

用法："展示所有进程"

Tool call: list_processes(host=None)

工具调用：list_processes(host=None)


**get_process_info** - Get detailed information about a specific process

```python


**get_process_info** - 获取特定进程的详细信息

```python

Usage: "What's using PID 1234?"

用法："PID 1234对应的进程是什么？"

Tool call: get_process_info(pid=1234, host=None)

工具调用：get_process_info(pid=1234, host=None)

undefined

undefined

Log Analysis

日志分析

read_journal - Read systemd journal logs

python

undefined

read_journal - 读取systemd日志

python

undefined

Usage: "Show last 50 journal entries"

用法："展示最近50条日志条目"

Tool call: read_journal(lines=50, unit=None, priority=None, host=None)

工具调用：read_journal(lines=50, unit=None, priority=None, host=None)

Priorities: "emerg", "alert", "crit", "err", "warning", "notice", "info", "debug"

优先级选项："emerg", "alert", "crit", "err", "warning", "notice", "info", "debug"


**read_log_file** - Read specific log files

```python


**read_log_file** - 读取特定日志文件

```python

Usage: "Show last 100 lines of /var/log/messages"

用法："展示/var/log/messages的最后100行"

Tool call: read_log_file(log_path="/var/log/messages", lines=100, host=None)

工具调用：read_log_file(log_path="/var/log/messages", lines=100, host=None)

Note: Log must be in LINUX_MCP_ALLOWED_LOGS

注意：日志文件必须在LINUX_MCP_ALLOWED_LOGS列表中


**search_logs** - Search for patterns in logs

```python


**search_logs** - 在日志中搜索指定模式

```python

Usage: "Search for 'error' in system logs"

用法："在系统日志中搜索'error'"

Tool call: search_logs(pattern="error", log_path="/var/log/messages", host=None)

工具调用：search_logs(pattern="error", log_path="/var/log/messages", host=None)

undefined

undefined

Network Diagnostics

网络诊断

get_network_info - Get network interface information

python

undefined

get_network_info - 获取网络接口信息

python

undefined

Usage: "What are the network interfaces?"

用法："有哪些网络接口？"

Tool call: get_network_info(host=None)

工具调用：get_network_info(host=None)


**get_listening_ports** - List listening network ports

```python


**get_listening_ports** - 列出正在监听的网络端口

```python

Usage: "What ports are listening?"

用法："哪些端口在监听？"

Tool call: get_listening_ports(host=None)

工具调用：get_listening_ports(host=None)


**test_connectivity** - Test network connectivity to a host

```python


**test_connectivity** - 测试与目标主机的网络连通性

```python

Usage: "Can we reach google.com?"

用法："能否连接到google.com？"

Tool call: test_connectivity(target="google.com", host=None)

工具调用：test_connectivity(target="google.com", host=None)

undefined

undefined

Storage Diagnostics

存储诊断

get_disk_usage - Get filesystem disk usage

python

undefined

get_disk_usage - 获取文件系统磁盘使用情况

python

undefined

Usage: "Show disk usage"

用法："展示磁盘使用情况"

Tool call: get_disk_usage(host=None)

工具调用：get_disk_usage(host=None)


**get_mount_points** - List mounted filesystems

```python


**get_mount_points** - 列出已挂载的文件系统

```python

Usage: "What's mounted on the system?"

用法："系统上挂载了哪些设备？"

Tool call: get_mount_points(host=None)

工具调用：get_mount_points(host=None)

undefined

undefined

Common Patterns

常见使用模式

Multi-Host Diagnostics

多主机诊断

python

undefined

python

undefined

Check multiple hosts in sequence

依次检查多个主机

"Check service status on web01, web02, and db01"

"检查web01、web02和db01上的服务状态"

Tool calls:

工具调用序列：

1. get_service_status(service_name="httpd", host="admin@web01")

2. get_service_status(service_name="httpd", host="admin@web02")

3. get_service_status(service_name="postgresql", host="admin@db01")

undefined

undefined

Service Troubleshooting Workflow

服务故障排查流程

python

undefined

python

undefined

"Troubleshoot why nginx isn't working on web01"

"排查web01上nginx无法运行的原因"

Typical tool sequence:

典型工具调用序列：

1. get_service_status(service_name="nginx", host="admin@web01")

2. read_journal(lines=100, unit="nginx", priority="err", host="admin@web01")

3. get_listening_ports(host="admin@web01") # Check if port 80/443 open

3. get_listening_ports(host="admin@web01") # 检查80/443端口是否开放

4. test_connectivity(target="localhost:80", host="admin@web01")

undefined

undefined

System Health Check

系统健康检查

python

undefined

python

undefined

"Run a health check on server01"

"对server01运行健康检查"

Tool sequence:

工具调用序列：

1. get_system_info(host="admin@server01")

2. list_services(host="admin@server01", state="failed")

3. get_disk_usage(host="admin@server01")

4. read_journal(lines=50, priority="err", host="admin@server01")

5. list_processes(host="admin@server01")

undefined

undefined

Log Analysis for Errors

错误日志分析

python

undefined

python

undefined

"Find authentication errors in the last hour"

"查找最近一小时内的认证错误"

Tool sequence:

工具调用序列：

1. read_journal(lines=1000, priority="err", host=None)

2. search_logs(pattern="authentication failure", log_path="/var/log/secure", host=None)

3. read_log_file(log_path="/var/log/audit/audit.log", lines=500, host=None)

undefined

undefined

Running the Server

运行服务器

Standalone Mode

独立模式

bash

undefined

bash

undefined

Run locally

本地运行

linux-mcp-server

With custom log access

自定义日志访问权限

LINUX_MCP_ALLOWED_LOGS="/var/log/myapp.log,/var/log/custom.log" linux-mcp-server

undefined

LINUX_MCP_ALLOWED_LOGS="/var/log/myapp.log,/var/log/custom.log" linux-mcp-server

undefined

Development Mode

开发模式

bash

undefined

bash

undefined

Clone and install in editable mode

克隆并以可编辑模式安装

git clone https://github.com/rhel-lightspeed/linux-mcp-server.git cd linux-mcp-server pip install -e .

Run with debugging

带调试模式运行

python -m linux_mcp_server

undefined

python -m linux_mcp_server

undefined

Troubleshooting

故障排查

SSH Connection Issues

SSH连接问题

Problem: "Could not connect to remote host"

Solutions:

Verify SSH key authentication:
```
ssh user@host
```
Check SSH agent is running:
```
echo $SSH_AUTH_SOCK
```

Start SSH agent:

eval $(ssh-agent)

and

ssh-add ~/.ssh/id_ed25519

Verify host in known_hosts:
```
ssh-keyscan host >> ~/.ssh/known_hosts
```

问题： "无法连接到远程主机"

解决方案：

验证SSH密钥认证：
```
ssh user@host
```
检查SSH代理是否运行：
```
echo $SSH_AUTH_SOCK
```

启动SSH代理：

eval $(ssh-agent)

并执行

ssh-add ~/.ssh/id_ed25519

验证主机是否在known_hosts中：
```
ssh-keyscan host >> ~/.ssh/known_hosts
```

Log Access Denied

日志访问被拒绝

Problem: "Log file not in allowed list"

Solution:

Add log path to
```
LINUX_MCP_ALLOWED_LOGS
```
environment variable
Restart the MCP server after updating configuration

json

{
  "env": {
    "LINUX_MCP_ALLOWED_LOGS": "/var/log/messages,/var/log/secure,/custom/app.log"
  }
}

问题： "日志文件不在允许列表中"

解决方案：

将日志路径添加到
```
LINUX_MCP_ALLOWED_LOGS
```
环境变量
更新配置后重启MCP服务器

json

{
  "env": {
    "LINUX_MCP_ALLOWED_LOGS": "/var/log/messages,/var/log/secure,/custom/app.log"
  }
}

Permission Denied Errors

权限被拒绝错误

Problem: "Permission denied" when accessing system resources

Solutions:

Use appropriate user with sudo privileges:
```
ssh admin@host
```
not
```
ssh user@host
```
Verify remote user has read access to logs and system commands
For systemctl commands, ensure user can run
```
systemctl status
```

问题： "访问系统资源时权限被拒绝"

解决方案：

使用具有sudo权限的合适用户：
```
ssh admin@host
```
而非
```
ssh user@host
```
验证远程用户对日志和系统命令具有读取权限
对于systemctl命令，确保用户可以运行
```
systemctl status
```

Tool Not Found

工具未找到

Problem: Command not found on remote system

Solutions:

Verify RHEL/systemd-based system (tool is optimized for RHEL)
Check required commands are installed:
```
systemctl
```
,
```
journalctl
```
,
```
ss
```
,
```
df
```
Ensure PATH includes
```
/usr/bin
```
,
```
/usr/sbin
```

问题： "远程系统上找不到命令"

解决方案：

验证系统是基于RHEL/systemd的（本工具针对RHEL优化）
检查所需命令是否已安装：
```
systemctl
```
,
```
journalctl
```
,
```
ss
```
,
```
df
```
确保PATH包含
```
/usr/bin
```
,
```
/usr/sbin
```

Security Considerations

安全注意事项

Read-only operations: All tools are strictly read-only, no system modifications
SSH key authentication: Use key-based auth, never passwords
Log access control: Explicitly whitelist allowed log files
Principle of least privilege: Use service accounts with minimal permissions
Audit logging: All SSH connections are logged on remote systems

只读操作：所有工具均为严格只读，不会修改系统
SSH密钥认证：使用基于密钥的认证，绝不使用密码
日志访问控制：明确白名单允许访问的日志文件
最小权限原则：使用具有最小权限的服务账户
审计日志：所有SSH连接都会在远程系统上记录日志

Best Practices

最佳实践

Use service accounts: Create dedicated accounts for MCP diagnostics
Limit log access: Only whitelist logs necessary for diagnostics
Test SSH first: Always verify manual SSH connection before using MCP
Monitor usage: Review SSH logs to track diagnostic sessions
Keep keys secure: Use SSH agent, don't embed keys in config files

使用服务账户：创建专门用于MCP诊断的账户
限制日志访问：仅白名单诊断所需的日志文件
先测试SSH：使用MCP前始终手动验证SSH连接
监控使用情况：查看SSH日志以跟踪诊断会话
保护密钥安全：使用SSH代理，不要在配置文件中嵌入密钥