Linux Info Mcp

linux-info-mcp

通过 SSH 在远程主机上运行只读诊断命令的 MCP 服务。包含 18 个模块中的 78 个工具：

• 文件：read_file、find_files、read_binary
• 归档：archive_list、archive_read
• systemctl：systemctl_status、systemctl_list、systemctl_list_timers、systemctl_list_sockets
• journalctl：journalctl
• 性能：iostat、vmstat、free、df、ps、psi_stats、meminfo
• 采样：sar、atop、pmrep
• 网络：ss、ip_addr、ip_route、lsof_net、arp_table、tc_qdisc、ethtool、conntrack、net_protocol_stats、nft_list、iptables_list、dig
• lldp：lldp_neighbors、lldp_interfaces、lldp_statistics、lldp_chassis
• proc：lsof、pgrep、pidof、top、proc_limits
• 磁盘：du、lsblk、blkid、smartctl、blockdev
• 内核：dmesg、uname、sysctl、slabtop、numastat、cgroup_stats、systemd_analyze
• 软件包：dpkg_list、rpm_list、apt_list_installed、reboot_required
• 系统：uptime、who、last、lscpu、lsmem、dmidecode、lspci、lsusb、sensors
• 时间：chronyc、timedatectl
• 文件系统：mount、findmnt、stat_fs、stat
• docker：docker_ps、docker_inspect、docker_images、docker_logs
• 主机信息：host_facts
• 分诊：triage

Agent 项目背景

权威规范：SPEC.md。 Agent 操作说明（约定、硬性规则、安全不变量、测试规范、添加工具检查清单）：AGENTS.md。 Claude Code 会自动加载 CLAUDE.md，该文件通过 @ 引入 AGENTS.md，以便 Claude Code 和任何会读取 AGENTS.md 的工具（Cursor、OpenAI Codex 等）使用同一信息源。

安装

uv sync

运行

uv run linux-info-mcp
# or
uv run python server.py

两种方式都会启动一个 stdio MCP 服务。

测试

uv run pytest -q

环境变量

变量	默认值	含义
LINUX_INFO_SSH_CMD	ssh	通过 shlex.split 解析的命令和标志（采用 shell 风格：引号和转义符均有效）；会成为 argv 前缀。例如：ssh -F /home/me/.ssh/config -o ConnectTimeout=5。设置后，完整 argv 由你负责（不会自动注入 mux 参数）。
LINUX_INFO_SSH_MUX	on	若未设置 LINUX_INFO_SSH_CMD，则默认 ssh 会启用 OpenSSH 连接多路复用（ControlMaster=auto、ControlPath=$TMPDIR/lim-%C、ControlPersist=60s），让重复调用复用同一连接，避免每次都进行握手。设置为 0/false/no/off 可禁用。
LINUX_INFO_HOSTS	``	以逗号分隔的精确主机名允许列表。留空 = 任意主机。
LINUX_INFO_TIMEOUT	30	子进程终止前的秒数。超时后：exit_code=124，并在 stderr 末尾追加 [timeout]。
LINUX_INFO_MAX_BYTES	1048576	stdout 和 stderr 的上限均为 1 MiB。read_binary 的 length 还会被限制为 floor((MAX_BYTES - 64) * 3 / 4)，以确保其 base64 流不会超出限制。
LINUX_INFO_MAX_HOSTS	10	每次多主机（hosts）调用的最大主机数。限制在 [1, 25]；25 是硬上限，用于防止 SSH 风暴。
LINUX_INFO_PARALLELISM	4	多主机扇出操作的工作线程数。限制在 [1, 25]，且不会超过主机数量。
LINUX_INFO_SUDO	``（关闭）	1/true/yes/on 会在可能需要特权的工具前加上 sudo -n（参见特权）。默认关闭。安全性取决于你的 sudoers 配置。
LINUX_INFO_OUTPUT_MODE	``（未设置）	将响应格式固定为 raw/parsed/both，覆盖每次调用的 output_mode 参数（参见输出模式）。无效值 → validation_error。
LINUX_INFO_LOG_FILE	``	JSONL 日志文件的绝对路径。留空或未设置 = 禁用日志记录。
LINUX_INFO_LOG_LEVEL	INFO	TRACE、DEBUG、INFO、WARNING、ERROR、CRITICAL。TRACE 会记录完整的工具调用 I/O 以及远程 SSH 命令和输出（详细）。

MCP 客户端配置

{
  "mcpServers": {
    "linux-info": {
      "command": "uv",
      "args": ["run", "--directory", "/abs/path/to/linux-info-mcp", "python", "server.py"],
      "env": {
        "LINUX_INFO_SSH_CMD": "ssh",
        "LINUX_INFO_SSH_MUX": "on",
        "LINUX_INFO_HOSTS": "",
        "LINUX_INFO_TIMEOUT": "30",
        "LINUX_INFO_MAX_BYTES": "1048576",
        "LINUX_INFO_MAX_HOSTS": "10",
        "LINUX_INFO_PARALLELISM": "4",
        "LINUX_INFO_SUDO": "",
        "LINUX_INFO_OUTPUT_MODE": "",
        "LINUX_INFO_LOG_FILE": "",
        "LINUX_INFO_LOG_LEVEL": "INFO"
      }
    }
  }
}

安全说明

• 从设计上确保只读。没有 -exec、-delete、写入重定向，也不会原样传递 find 谓词。
• 本地 subprocess.run 始终使用 shell=False。远程命令是一个经过 shell 引号处理的字符串，作为单个 ssh 参数传递。
• 每个插值的值都会经过 shlex.quote 处理。包含 NUL 或换行符的输入会在处理引号前被拒绝。
• grep_flags 会根据白名单进行验证（-i、-E、-v、-n、-w、-F 和 -C1..-C9）。
• find 只接受经过验证的命名谓词：name、iname、type、maxdepth、mindepth、mtime、size、path_glob。
• 如果主机名包含空白字符或以 - 开头，则会被拒绝。如果设置了 LINUX_INFO_HOSTS，主机名必须与其中某个条目完全匹配。
• 远程命令会以 LC_ALL=C 为前缀，以确保输出稳定。

日志记录

默认关闭 JSONL 文件日志。设置 LINUX_INFO_LOG_FILE=/path/to/log.jsonl 可启用。每行是一条事件：

{"ts":"2026-05-30T12:34:56.789+00:00","level":"INFO","logger":"linux_info_mcp.ssh","msg":"ssh_call","host":"h1","exit_code":0,"duration_ms":42.5,"stdout_bytes":1234,"truncated":false,"outcome":"ok","pid":12345,"tool":"read_file","request_id":"a1b2c3d4e5f6"}

INFO 级别会输出 server_start、server_stop、tool_call（包含 tool、host、duration_ms、exit_code、outcome；多主机调用会添加 host_count，将 host 设为 null，并在任一主机失败时报告 outcome: partial）和 ssh_call（包含 host、exit_code、duration_ms、stdout_bytes、stderr_bytes、truncated；扇出时每个主机对应一条记录，所有记录共用该调用的 request_id）。TRACE 还会输出完整的工具参数、工具结果、远程命令字符串以及远程 stdout/stderr。完整表格请参阅 SPEC.md §Logging。

run_ssh 是集中计时和日志记录的环节；它会将 duration_ms 写入 SshResult，并为每次调用输出一条 ssh_call 日志。_call_tool 是工具级集中计时和日志记录的环节，涵盖验证和分发。

工具调用期间的每条日志都带有 tool（MCP 工具名称）和 request_id（每次调用生成的 12 位十六进制 ID）。服务日志和 SSH 日志通过 request_id 关联；ssh_call 会显示触发该调用的工具。每条日志——包括工具调用之外的日志——还带有 pid（进程 ID），以便区分共享同一日志文件的并发服务进程。

并发

工具处理函数是同步的（它们会调用阻塞式 subprocess.run 执行 ssh）。异步 MCP 入口点会通过 asyncio.to_thread 分发各处理函数，因此 Agent 发起的并发 call_tool 请求会在线程池中运行，而不会在事件循环上串行执行。因此，N 个并行工具调用的墙钟时间为 max(durations)，而非 sum(durations)；这对基于 teleport 的 SSH 尤其重要，因为每次握手需要 0.5–2s。

多主机扇出

每个工具接受单个 host（字符串）或 hosts 列表（数组）——两者不能同时使用。使用 hosts 时，工具会并行地在每台主机上运行，并返回：

{"multi_host": true, "host_count": 2, "results": [
  {"host": "h1", "stdout": "...", "stderr": "", "exit_code": 0, "truncated": false, "stderr_truncated": false},
  {"host": "h2", "error": "RuntimeError: ...", "outcome": "handler_error"}
]}

results 按输入顺序排列（去重后）。各主机的失败相互隔离——一台主机故障不会中止其他主机；此时整体 tool_call 的 outcome 为 partial。主机数量上限由 LINUX_INFO_MAX_HOSTS 控制（默认值为 10，硬上限为 25）；扇出会运行 LINUX_INFO_PARALLELISM 个工作线程（默认值为 4）。单个 host 会返回未经更改的常规扁平字典。

输出模式

传入 output_mode 以控制响应结构：raw（默认，stdout 文本）、parsed（结构化对象，不包含 stdout）或 both。LINUX_INFO_OUTPUT_MODE 可在服务端锁定输出模式，并覆盖参数。带有解析器的工具（目前为 df、free）会填充 parsed；其他工具会报告 parse_status: "unsupported" 并回退到 raw。截断输出或非零输出绝不会被解析。

// df with {"host": "h1", "output_mode": "parsed"}
{"parsed": [
  {"fs": "/dev/sda1", "blocks_1k": 41252336, "used_1k": 8765432,
   "avail_1k": 30387654, "use_pct": 23, "mount": "/"}
], "stderr": "", "exit_code": 0, "truncated": false,
 "stderr_truncated": false, "parse_status": "ok"}

权限

服务以你的 SSH 登录用户身份运行，不会自行提升权限。需要 root 权限的工具（smartctl、dmidecode、nft_list、iptables_list、conntrack、通常还有 dmesg、某些模式下的 ethtool 以及 lldp_* 工具）否则会因权限错误而失败。

**检测（始终启用）：**命令失败且 stderr 看起来像权限错误时，其结果会添加 privilege_error: true，让 Agent 知道应使用特权路径，而不是自行猜测。每个结果还包含 error_kind（ok/timeout/auth/dns/unreachable/not_found/privilege/nonzero），让 Agent 能选择重试、切换主机、提升权限或放弃。

**权限提升（可选）：**设置 LINUX_INFO_SUDO=1，即可在上述易受权限限制的工具前添加 sudo -n（非交互式）——仅限这些工具。服务只是执行机制；**它实际能做什么完全由你的 sudoers 决定。**请严格限制范围：

# /etc/sudoers.d/linux-info  — dedicated read-only diag account
diag ALL=(root) NOPASSWD: /usr/sbin/smartctl, /usr/sbin/dmidecode, \
  /usr/sbin/nft -nn list *, /usr/sbin/iptables -n -v -L *, /usr/sbin/conntrack

LINUX_INFO_SUDO=1 配上宽松的 sudoers（NOPASSWD: ALL）会让大模型获得实际的 root 权限——服务无法阻止这一点。切勿使用一概而论的 sudo sh -c；只有按工具分别使用 sudo -n，受限的 sudoers 才能将其严格锁定。（对于 Docker，建议将登录用户添加到 docker 组，而不是使用 sudo。）

限制

• 每次调用仅返回一次响应。不支持流式传输；stdout 上限为 LINUX_INFO_MAX_BYTES，达到上限时会设置 truncated: true。
• SSH 身份验证由用户的 ssh 配置或 Agent 处理。本服务不会处理凭据。

安全性

有关漏洞报告政策和威胁模型，请参阅 SECURITY.md。

许可证

MIT。请参阅 LICENSE。