Linux Info Mcp

linux-info-mcp

SSH 経由でリモートホスト上の読み取り専用診断コマンドを実行する MCP サーバーです。18 のモジュールにまたがる 78 個のツールを提供します。

• files：read_file、find_files、read_binary
• archive：archive_list、archive_read
• systemctl：systemctl_status、systemctl_list、systemctl_list_timers、systemctl_list_sockets
• journalctl：journalctl
• perf：iostat、vmstat、free、df、ps、psi_stats、meminfo
• sampling：sar、atop、pmrep
• net：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
• disk：du、lsblk、blkid、smartctl、blockdev
• kernel：dmesg、uname、sysctl、slabtop、numastat、cgroup_stats、systemd_analyze
• pkg：dpkg_list、rpm_list、apt_list_installed、reboot_required
• sys：uptime、who、last、lscpu、lsmem、dmidecode、lspci、lsusb、sensors
• time：chronyc、timedatectl
• fs：mount、findmnt、stat_fs、stat
• docker：docker_ps、docker_inspect、docker_images、docker_logs
• facts：host_facts
• triage：triage

エージェント向けプロジェクト情報

正式な仕様書：SPEC.md。 エージェントの運用ガイド（規約、厳守事項、セキュリティ上の不変条件、テストの方針、ツール追加チェックリスト）：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 で解析されるコマンドとフラグ（シェル形式：引用符とエスケープを解釈）。argv のプレフィックスになります。例：ssh -F /home/me/.ssh/config -o ConnectTimeout=5。設定すると、argv 全体を指定したものとして扱われます（多重化設定は自動で追加されません）。
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 にはさらに上限が適用され、base64 ストリームが収まるよう floor((MAX_BYTES - 64) * 3 / 4) に制限されます。
LINUX_INFO_MAX_HOSTS	10	複数ホスト（hosts）呼び出しごとの最大ホスト数です。[1, 25] の範囲に制限されます。SSH 接続の集中を防ぐため、25 が上限です。
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 を指定すると、ツール呼び出しの入出力全体と、リモートの 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 を使用します。リモートコマンドはシェル用にクォートした単一の文字列として、1 つの 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 を設定します。各行は 1 件のイベントです。

{"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 を含みます。ファンアウトではホストごとに 1 件のエントリが記録され、すべて同じ呼び出しの request_id を共有します）が出力されます。TRACE では、ツールの全引数、ツールの結果、リモートコマンド文字列、リモートの stdout/stderr も出力されます。全項目の表は SPEC.md §Logging を参照してください。

run_ssh はタイミングとロギングの中心となる箇所です。SshResult に duration_ms を記録し、呼び出しごとに ssh_call のログエントリを 1 件出力します。_call_tool は検証とディスパッチを含む、ツールレベルのタイミングとロギングの中心となる箇所です。

ツール呼び出し中のすべてのログ行には、tool（MCP ツール名）と request_id（呼び出しごとに生成される 12 桁の 16 進数 ID）が含まれます。サーバーログと SSH ログは request_id で関連付けられます。ssh_call から、どのツールが呼び出しを行ったかを確認できます。ツール呼び出し以外のものも含め、すべてのログ行には pid（プロセス ID）も含まれるため、同じログファイルを共有する並行サーバープロセスを区別できます。

並行処理

ツールハンドラーは同期処理です（ssh のためにブロッキングする subprocess.run を呼び出します）。非同期 MCP エントリーポイントは各ハンドラーを asyncio.to_thread 経由でディスパッチするため、エージェントからの並行する call_tool リクエストは、イベントループ上で順番に処理されず、スレッドプールで実行されます。そのため、N 件のツール呼び出しを並行して実行した場合の実時間は sum(durations) ではなく max(durations) になります。各ハンドシェイクに 0.5～2 秒かかる、teleport を使用した SSH では特に重要です。

複数ホストへのファンアウト

すべてのツールは、単一の 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 は入力順（重複排除済み）に並びます。ホストごとの失敗は個別に処理されるため、1 つのホストで問題が発生してもほかのホストの処理は中断されません。この場合、全体の tool_call の outcome は partial になります。ホスト数の上限は LINUX_INFO_MAX_HOSTS で設定します（デフォルトは 10、ハード上限は 25）。ファンアウトでは LINUX_INFO_PARALLELISM 個のワーカーを実行します（デフォルトは 4）。host を 1 つだけ指定した場合は、従来どおり変更のないフラットな辞書を返します。

出力モード

output_mode を指定して、応答の形式を制御できます。raw（デフォルト、stdout のテキスト）、parsed（構造化オブジェクト、stdout は除外）、または both を指定します。LINUX_INFO_OUTPUT_MODE が設定されている場合はサーバー側で固定され、引数より優先されます。パーサーがあるツール（現在は df、free）は parsed を設定します。それ以外のツールは parse_status: "unsupported" を報告し、raw にフォールバックします。切り詰められた出力や、終了コードが 0 以外の出力は解析されません。

// 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 が追加されるため、エージェントは推測せず、権限を使う方法に切り替えられます。すべての結果には error_kind（ok／timeout／auth／dns／unreachable／not_found／privilege／nonzero）も含まれるため、エージェントは再試行するか、ホストを切り替えるか、権限を昇格するか、諦めるかを判断できます。

権限昇格（オプトイン）： 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）を組み合わせると、LLM に実質的な root 権限が渡されます。サーバーではこれを防げません。包括的な sudo sh -c は決して使わないでください。制約を設けた sudoers で制限できるのは、ツールごとの sudo -n だけです。（Docker の場合は、sudo よりもログインユーザーを docker グループに追加する方法を推奨します。）

制限事項

• 呼び出しごとに応答は 1 回だけです。ストリーミングには対応していません。stdout は LINUX_INFO_MAX_BYTES で上限が設定され、上限に達すると truncated: true が設定されます。
• SSH 認証はユーザーの ssh 設定／エージェントに委ねられます。このサーバーが認証情報を扱うことはありません。

セキュリティ

脆弱性の報告方針と脅威モデルについては、SECURITY.md を参照してください。

ライセンス

MIT。詳細は LICENSE を参照してください。