LogMCP 是一个开源 MCP 服务器，用于让 AI 助手以只读方式访问远程 Linux 服务器上的日志文件，从而在不授予 AI shell 访问权限的前提下辅助调试。AI 通过 HTTPS 连接，服务器保持完全可控。
用途 LogMCP 面向需要 AI 辅助调试、但无法或不愿授予 shell 访问权限的场景，例如生产服务器、客户机器、加固环境或任何重视最小权限的部署。AI 可以像普通 HTTPS 客户端一样连接，无需 SSH，没有写权限，也无法执行任何操作，甚至不能读取白名单日志路径之外的内容。每次访问都会通过服务器上的 syslog 进行审计。
主要能力
- 对日志文件的只读访问，AI 无法修改任何内容。
- 白名单/黑名单 glob 模式，实现细粒度访问控制。
- 将 systemd journal（journald://）作为虚拟日志源。
- 多令牌认证：每个客户端使用独立 bearer token，并支持撤销。
- 外部认证器支持：可将令牌验证委托给任意 CLI 程序。
- TLS 支持：自签名证书、自定义证书，或置于 Caddy 反向代理之后。
- 通过 syslog 记录审计轨迹（仅记录访问，不记录日志内容）。
- 引导式交互设置向导。
- systemd 服务集成。
- 扩展：将外部 CLI 工具或 Redis-RPC worker 暴露为额外的 MCP 工具。
- 宏：用 YAML 文件定义复合 MCP 工具，无需编写代码。
- fail2ban 集成和进程内速率限制。
使用方式 LogMCP 提供两种安装方式。
方式 A：快速启动（无需 root） 可在不到一分钟内试用，无需配置文件、root 或 systemd。命令会检查用户所属组（adm、systemd-journal），生成 bearer token 和自签名 TLS 证书，启动服务器，并打印可直接粘贴的 claude mcp add 命令。如果以 root 运行，可传入 --user <name>，LogMCP 会将用户加入所需组并以该用户重新启动，后续启动不再需要 root。注意：令牌和证书是临时的，令牌每次启动都会变化；永久设置请使用方式 B。测试后可从 Claude Code 中移除服务器。
方式 B：永久安装（推荐） 安装预构建的 .deb 包（将 x.y.z 替换为最新版本）。然后运行设置向导，它会引导完成 TLS 模式、bearer token 和 systemd 服务配置，并打印可直接粘贴的客户端配置片段。最后将输出粘贴到 MCP 客户端配置中，AI 即可读取服务器日志。
设置向导（sudo logmcp setup）涵盖：部署模式（直接 TLS 或置于 Caddy 之后）、端口和 bearer token 配置、systemd 服务安装、以及 Claude Code、VS Code、Claude Desktop 的客户端配置片段。白名单/黑名单和 journald 在设置后直接于 /etc/logmcp/config.yaml 中配置。
配置支持环境变量替换：config.yaml 中的任何值都可以使用 ${VAR} 或 $VAR 语法引用环境变量，替换在解析文件之前进行，因此令牌、路径、DSN 等均可使用。未设置的变量展开为空字符串；如需保留字面量 $，使用 $$。
设置完成后启动服务器。LogMCP 向 AI 助手暴露内置工具；扩展可能添加更多工具，其名称以扩展名称为前缀（例如名为 myapp 的扩展会提供 myapp_status）。
扩展：将外部工具包装为 MCP LogMCP 可以将任何外部程序或服务暴露为额外的 MCP 工具，无需自定义 MCP 服务器。AI 会像看到内置日志工具一样看到它们。任何实现 clitool 接口（list / call 子命令）的程序都可以注册。LogMCP 在启动时调用 <command> list 发现工具，并将每次工具调用转发到 <command> call <tool> --token-stdin。这种方式每次调用都会生成子进程，适用于同一主机或远程主机上的任何程序。
RPC 扩展（Redis） 对于运行在同一主机上的程序，RPC 变体可避免每次调用的进程启动开销（对 Python 程序尤其明显，解释器启动和导入会带来可感知延迟）。LogMCP 不生成子进程，而是将请求推送到 Redis 列表并等待 worker 回复。worker 从 Redis 列表读取请求，并将回复推送到每个请求对应的回复键。完整协议见 docs/RPC.md。
每个传入 MCP 请求的 bearer token 都会转发给扩展——CLI 模式通过 stdin，RPC 模式作为调用方元数据放在 RPC 信封中。扩展可以验证它，或信任已解析的身份。
SSH 隧道设置 如果本地使用 Claude Code 且已拥有服务器的 SSH 访问权限，可以在没有公共 HTTPS 端点的情况下运行 LogMCP。通过隧道时 LogMCP 仍要求 bearer token：SSH 层提供传输安全，令牌控制哪个客户端可以连接。
适用场景 实际案例见 docs/case-studies.md，包括：Asterisk/VoIP 调试包编译和依赖错误；使用 Caddy 反向代理的 Web 服务器生产安装；使用自有 TLS 的独立运行。
限制 LogMCP 仅提供只读访问，AI 无法修改、删除或执行任何内容，也无法读取白名单日志路径之外的内容。快速启动模式下令牌和证书是临时的，令牌每次启动都会变化。审计仅记录访问，不记录日志内容。
许可 MIT License，详见 LICENSE。
