linux-mcp

Name: linux-mcp
Author: marcos2872

作者：marcos28722 星标更新：2025-11-03

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

项目介绍

Linux MCP Server

用Rust编写的MCP（模型上下文协议）服务器，提供获取Linux系统信息和通过PolicyKit安全认证在终端执行命令的工具。

🔐 安全性：此服务器使用PolicyKit（pkexec）进行root命令的身份验证——系统会弹出一个原生窗口请求您的密码，该密码永远不会通过MCP传输！

📖 文档

🚀 在Claude Desktop上配置 - 完整的分步指南
📋 快速参考 - 即用示例
🔐 PolicyKit指南 - 高级安全配置

⚡ 快速开始 - 使用root权限执行命令

要执行需要管理员权限的命令（如apt update，systemctl restart等），添加use_polkit: true：

✅ PolicyKit - 系统原生图形窗口

{
  "name": "execute_command",
  "arguments": {
    "command": "apt",
    "args": ["update"],
    "use_polkit": true
  }
}

会发生什么：系统会弹出一个原生窗口请求您的密码（就像您安装程序时一样）。您的密码永远不会通过MCP发送——操作系统负责安全的身份验证。

⚠️ 常见错误

❌ 错误（会导致“权限被拒绝”）：

{
  "command": "apt",
  "args": ["update"]
}

✅ 正确（添加use_polkit: true）：

{
  "command": "apt",
  "args": ["update"],
  "use_polkit": true
}

🚀 功能

🛠️ 工具

get_system_info：获取详细的系统信息
- CPU（数量、型号、使用率）
- 内存（总量、已用、可用、交换空间）
- 磁盘（总空间、可用空间、文件系统）
- 操作系统（名称、内核版本、主机名）
execute_command：在终端执行命令
- 返回stdout、stderr和退出码
- 支持命令参数
- 两种执行模式：
  - 普通（默认）：以当前用户权限执行
  - PolicyKit（use_polkit: true）：使用pkexec并显示系统原生图形窗口——推荐用于需要root权限的命令
- ⚠️ 小心使用——可以执行任何系统命令

📚 资源

无需执行命令即可访问系统信息：

linux://logs/system - 系统日志的最后100行（journalctl）
linux://logs/auth - 最近50条SSH认证日志
linux://config/network - 当前网络配置（ip addr show）
linux://processes/top - 按内存使用量排名的前10个进程
linux://system/status - 系统总体状态（CPU、内存、运行时间）

💡 提示

引导式完成常见的管理任务：

system_troubleshooting - 交互式诊断问题（CPU、内存、磁盘、网络、进程）
security_audit - 系统安全审计（基本或全面范围）
service_management - 管理systemd服务（状态、启动、停止、重启、启用、禁用）
log_analysis - 日志分析（系统、认证、内核、应用程序）
disk_cleanup - 安全清理磁盘（保守或激进模式）

📦 编译

cargo build --release

二进制文件将生成在target/release/linux-mcp

🔧 使用

运行服务器

./target/release/linux-mcp

服务器通过标准I/O（stdin/stdout）遵循MCP协议进行通信。

与Claude Desktop集成

🤖 详细指南：请参阅CLAUDE_DESKTOP_SETUP.md获取完整的逐步说明！

快速概览：

编译：cargo build --release
编辑：~/.config/Claude/claude_desktop_config.json（Linux）
添加配置：

{
  "mcpServers": {
    "linux-mcp": {
      "command": "/完整路径到/linux-mcp-wrapper.sh",
      "args": [],
      "env": {}
    }
  }
}

完全重启Claude Desktop

配置路径：

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

与Cursor IDE / VS Code集成

选项1：项目级配置

在项目的根目录创建.cursor/mcp_config.json（Cursor）或.vscode/mcp.json（VS Code）文件：

# 对于Cursor
mkdir -p .cursor
nano .cursor/mcp_config.json

# 对于VS Code
mkdir -p .vscode
nano .vscode/mcp.json

文件内容：

{
  "mcpServers": {
    "linux-mcp": {
      "command": "/home/marcos/Documents/Pessoal/linux-mcp/target/release/linux-mcp",
      "args": [],
      "env": {}
    }
  }
}

选项2：全局配置

在~/.config/cursor/mcp_config.json或~/.config/Code/User/mcp.json中进行全局配置

使用MCP Inspector测试

npx @modelcontextprotocol/inspector /完整路径到/linux-mcp

📚 使用示例

🛠️ 工具

获取完整的系统信息

{
  "name": "get_system_info",
  "arguments": {
    "info_type": "all"
  }
}

仅获取CPU信息

{
  "name": "get_system_info",
  "arguments": {
    "info_type": "cpu"
  }
}

执行普通命令（无root权限）

{
  "name": "execute_command",
  "arguments": {
    "command": "ls",
    "args": ["-la", "/home"]
  }
}

⭐ 使用PolicyKit执行命令（用于需要root权限的命令）

{
  "name": "execute_command",
  "arguments": {
    "command": "apt",
    "args": ["update"],
    "use_polkit": true
  }
}

结果：系统原生窗口请求密码 → 安全执行命令 ✅

会发生什么：一个官方系统图形窗口出现，请求您的管理员密码（就像您通过应用中心安装程序时一样）。

📚 资源

资源提供了无需执行命令即可直接访问系统信息的方式：

读取系统日志

{
  "method": "resources/read",
  "params": {
    "uri": "linux://logs/system"
  }
}

查看网络配置

{
  "method": "resources/read",
  "params": {
    "uri": "linux://config/network"
  }
}

检查内存使用量最高的进程

{
  "method": "resources/read",
  "params": {
    "uri": "linux://processes/top"
  }
}

查看系统总体状态

{
  "method": "resources/read",
  "params": {
    "uri": "linux://system/status"
  }
}

💡 提示

提示引导您完成常见的管理任务：

CPU故障排除

{
  "method": "prompts/get",
  "params": {
    "name": "system_troubleshooting",
    "arguments": {
      "problem_type": "cpu"
    }
  }
}

全面的安全审计

{
  "method": "prompts/get",
  "params": {
    "name": "security_audit",
    "arguments": {
      "scope": "full"
    }
  }
}

管理nginx服务

{
  "method": "prompts/get",
  "params": {
    "name": "service_management",
    "arguments": {
      "service_name": "nginx",
      "action": "restart"
    }
  }
}

分析认证日志

{
  "method": "prompts/get",
  "params": {
    "name": "log_analysis",
    "arguments": {
      "log_type": "auth",
      "priority": "warning"
    }
  }
}

激进地清理磁盘

{
  "method": "prompts/get",
  "params": {
    "name": "disk_cleanup",
    "arguments": {
      "aggressive": "true"
    }
  }
}

⚠️ 重要：对于需要root权限的命令，请添加`use_polkit: true`

需要root权限的命令（如apt update，systemctl restart等）必须包括提升方法：

无提升方法的命令 ❌	正确的命令 ✅
`"command": "apt", "args": ["update"]`	`"command": "apt", "args": ["update"], "use_polkit": true`
`"command": "systemctl", "args": ["restart", "nginx"]`	`"command": "systemctl", "args": ["restart", "nginx"], "use_polkit": true`

✅ PolicyKit更安全：显示身份验证的图形对话框，并允许细粒度的权限控制。请参阅完整的PolicyKit指南获取详细说明。

🔐 PolicyKit - 使用root权限的安全认证

PolicyKit是Linux原生的管理员特权认证系统。

⭐ 为什么使用PolicyKit？

✅ 安全：图形身份验证对话框——密码不会暴露在日志中
✅ 细粒度控制：按命令和用户设置权限
✅ 审计：系统日志中的完整记录
✅ 自动超时：凭据自动过期
✅ 原生：您的Linux桌面环境（GNOME、KDE、XFCE等）的官方接口

📦 安装

# Ubuntu/Debian
sudo apt install polkitd policykit-1

# Fedora/RHEL
sudo dnf install polkit

# Arch Linux
sudo pacman -S polkit

检查安装：

which pkexec
systemctl status polkit

🚀 基本使用

{
  "name": "execute_command",
  "arguments": {
    "command": "systemctl",
    "args": ["restart", "nginx"],
    "use_polkit": true
  }
}

会发生什么：

MCP执行pkexec systemctl restart nginx
系统弹出一个原生窗口（不是自定义的——是Linux官方的）
您输入管理员密码
PolicyKit验证并以特权执行命令
结果返回给MCP

窗口外观：

GNOME/Ubuntu：带有红色/黄色盾牌的“身份验证所需”窗口
KDE Plasma：KDE Polkit Agent的蓝色对话框
XFCE/MATE：特定环境的简单窗口

✅ 您的密码永远不会通过MCP发送——操作系统负责身份验证！

⚙️ 高级配置（可选）

为了允许某些命令无需密码，创建自定义规则：

# 复制示例文件
sudo cp examples/polkit/50-linux-mcp.rules /etc/polkit-1/rules.d/

# 编辑为您的用户
sudo nano /etc/polkit-1/rules.d/50-linux-mcp.rules

# 重启polkit
sudo systemctl restart polkit

📖 完整指南：请参阅examples/polkit/README_POLKIT.md获取详细说明、示例和故障排除。

🔧 PolicyKit故障排除

❌ 问题：身份验证窗口未出现

原因：MCP没有访问图形会话。

解决方案1：在MCP中配置环境变量

{
  "mcpServers": {
    "linux-mcp": {
      "command": "/完整路径到/linux-mcp",
      "env": {
        "DISPLAY": ":0",
        "XAUTHORITY": "/home/您的用户/.Xauthority",
        "DBUS_SESSION_BUS_ADDRESS": "unix:path=/run/user/1000/bus"
      }
    }
  }
}

解决方案2：检查polkit代理是否正在运行

# 检查进程
ps aux | grep polkit

# 手动启动（GNOME/Ubuntu）
/usr/libexec/polkit-gnome-authentication-agent-1 &

# 手动启动（KDE）
/usr/lib/polkit-kde-authentication-agent-1 &

❌ 问题：“PolicyKit (pkexec)未安装”

解决方案：安装PolicyKit

# Ubuntu/Debian
sudo apt install policykit-1 polkitd

# Fedora/RHEL
sudo dnf install polkit

# Arch Linux
sudo pacman -S polkit

检查安装：

which pkexec
systemctl status polkit

❌ 问题：“未经授权”或“身份验证失败”

原因：您的用户没有权限或PolicyKit规则阻止了它。

解决方案：配置PolicyKit规则

# 复制规则示例
sudo cp examples/polkit/50-linux-mcp.rules /etc/polkit-1/rules.d/

# 编辑并替换“marcos”为您的用户
sudo nano /etc/polkit-1/rules.d/50-linux-mcp.rules

# 重启polkit
sudo systemctl restart polkit

查看错误日志：

journalctl -u polkit -f

❌ 问题：执行命令时“权限被拒绝”

原因：您忘记添加use_polkit: true。

错误示例：

{
  "exit_code": 100,
  "stderr": "E: 无法打开锁文件 - open (13: 权限被拒绝)",
  "elevation_method": "none"
}

解决方案：添加提升方法：

{
  "command": "apt",
  "args": ["update"],
  "use_polkit": true // ← 添加这个！
}

🔍 调试：查看发生了什么

# 实时查看PolicyKit的日志
journalctl -u polkit -f

# 在终端手动测试pkexec
pkexec systemctl status nginx

# 查看所有可用的PolicyKit操作
pkaction

# 检查环境变量
echo $DISPLAY
echo $DBUS_SESSION_BUS_ADDRESS

⚠️ 安全性

execute_command工具可以在系统上执行任何命令。

已实施的安全措施：

✅ PolicyKit：通过系统原生窗口进行身份验证——密码不会暴露
✅ 无sudo/密码：MCP不存储或传输任何密码
✅ 审计：所有使用PolicyKit的命令都会记录在系统日志中

最佳实践：

对所有需要root权限的命令使用PolicyKit（use_polkit: true）
配置特定命令的PolicyKit规则（参见examples/polkit/）
监控日志：journalctl -u polkit -f
不要以root身份运行服务器

📝 许可证

本项目是开源的，采用MIT许可证。

🤝 贡献

欢迎贡献！随时提出issues或pull requests。

linux-mcp

项目介绍

Linux MCP Server

📖 文档

⚡ 快速开始 - 使用root权限执行命令

✅ PolicyKit - 系统原生图形窗口

⚠️ 常见错误

🚀 功能

🛠️ 工具

📚 资源

💡 提示

📦 编译

🔧 使用

运行服务器

与Claude Desktop集成

与Cursor IDE / VS Code集成

选项1：项目级配置

选项2：全局配置

使用MCP Inspector测试

📚 使用示例

🛠️ 工具

获取完整的系统信息

仅获取CPU信息

执行普通命令（无root权限）

⭐ 使用PolicyKit执行命令（用于需要root权限的命令）

📚 资源

读取系统日志

查看网络配置

检查内存使用量最高的进程

查看系统总体状态

💡 提示

CPU故障排除

全面的安全审计

管理nginx服务

分析认证日志

激进地清理磁盘

⚠️ 重要：对于需要root权限的命令，请添加use_polkit: true

🔐 PolicyKit - 使用root权限的安全认证

⭐ 为什么使用PolicyKit？

📦 安装

🚀 基本使用

⚙️ 高级配置（可选）

🔧 PolicyKit故障排除

❌ 问题：身份验证窗口未出现

❌ 问题：“PolicyKit (pkexec)未安装”

❌ 问题：“未经授权”或“身份验证失败”

❌ 问题：执行命令时“权限被拒绝”

🔍 调试：查看发生了什么

⚠️ 安全性

📝 许可证

🤝 贡献

⚠️ 重要：对于需要root权限的命令，请添加`use_polkit: true`