logmcp

LogMCP

MCP 服务——为 AI 助手提供只读日志访问。借助 AI 调试 Linux 服务，无需向 AI 提供 shell 访问权限。

无需 SSH。无需写入权限。AI 通过 HTTPS 读取日志并帮助你诊断问题，同时你的服务始终完全由你掌控。

LogMCP 是一款开源 MCP 服务，可向 AI 助手（Claude Code、VS Code、Claude Desktop）开放远程 Linux 服务上的日志文件。访问权限为只读，通过令牌进行身份验证，并通过 syslog 进行完整审计。

快速开始

选项 A：快速启动（无需 root）

不到一分钟即可试用 LogMCP——无需配置文件、无需 root、无需 systemd：

logmcp quickstart

该命令会检查你的组成员身份（adm、systemd-journal），生成 bearer 令牌和自签名 TLS 证书，启动服务，并输出一条可直接粘贴的 claude mcp add 命令。

以 root 身份运行？ 传入 --user <name>，LogMCP 就会将该用户添加到所需的组中，并以该用户身份重新启动——之后启动时无需 root。

注意： 令牌和证书都是临时的。每次启动时令牌都会变化。若需永久配置，请使用选项 B。

logmcp quickstart --port 7789 --token mytoken   # optional flags

测试完成后，从 Claude Code 中移除该服务：

claude mcp remove logmcp-quickstart

---

选项 B：永久安装（推荐）

1. 安装

go install github.com/kascada/logmcp@latest

或者安装预构建的 .deb（将 x.y.z 替换为最新版本）：

curl -LO https://github.com/kascada/logmcp/releases/download/vx.y.z/logmcp_x.y.z_amd64.deb
sudo dpkg -i logmcp_x.y.z_amd64.deb

2. 运行设置向导

sudo logmcp setup

向导会引导你配置 TLS 模式、bearer 令牌和 systemd 服务，然后输出一段可直接粘贴的客户端配置片段。

3. 添加到 AI 客户端

logmcp client-config claude-code   # or: vscode | claude-desktop

将输出粘贴到 MCP 客户端配置中即可。完成后，你的 AI 就可以读取服务的日志了。

---

核心优势：让 AI 调试，而不触碰你的服务

你只需向 AI 开放一个只读的日志窗口。

• 无需 SSH 访问权限——AI 会像任何 HTTPS 客户端一样连接
• 无需写入权限——AI 无法更改、删除或执行任何内容
• 无 shell 访问权限——甚至无法读取白名单日志路径之外的内容
• 随时随地均可使用——你的笔记本电脑、Claude Desktop 或远程 CI Agent
• 服务上的每次访问都会通过 syslog 进行审计

因此，当你需要 AI 辅助调试，却无法或不希望授予 shell 访问权限时，LogMCP 是理想选择：例如生产服务、客户机器、强化安全的环境，或任何需要遵循最小权限原则的场景。

也支持 SSH。 如果你的 AI 客户端是使用 SSH 密钥在本地运行的 Claude Code，可以通过 SSH 隧道使用 LogMCP，而无需公开 HTTPS 端点。请参阅下方的SSH 隧道设置。

功能

• 只读访问日志文件——AI 无法修改任何内容
• 使用白名单/黑名单 glob 模式进行精细访问控制
• 将 systemd 日志（journald://）作为虚拟日志源
• 多令牌身份验证——支持按客户端配置 bearer 令牌并撤销令牌
• 支持外部身份验证器——将令牌验证委托给任意 CLI 程序
• 支持 TLS：自签名证书、自定义证书，或部署在 Caddy 反向代理后方
• 通过 syslog 进行审计（仅记录访问情况，不记录日志内容）
• 交互式设置向导
• 集成 systemd 服务
• 扩展——将外部 CLI 工具或 Redis-RPC 工作进程作为额外的 MCP 工具开放
• 宏——以 YAML 文件定义组合式 MCP 工具，无需编写代码
• 集成 fail2ban，并支持进程内速率限制

设置详情

向导（sudo logmcp setup）涵盖以下内容：

• 部署模式（直接使用 TLS 或部署在 Caddy 后方）
• 端口和 bearer 令牌配置
• systemd 服务安装
• Claude Code、VS Code 和 Claude Desktop 的客户端配置片段

白名单/黑名单和 journald 可在设置完成后直接通过 /etc/logmcp/config.yaml 配置。

环境变量替换

config.yaml 中的任何值都可以使用 ${VAR} 或 $VAR 语法引用环境变量。替换会在解析文件之前进行，因此适用于任何位置——令牌、路径、DSN 等。

auth:
  tokens:
    - name: claude
      token: ${LOGMCP_TOKEN}
      scopes: [read]

extensions:
  clitool:
    - name: switchboard
      command: /usr/local/bin/switchboard
      timeout_seconds: 10

未设置的变量会展开为空字符串。若要在值中保留字面量 $，请使用 $$。

设置完成后，启动服务：

sudo systemctl start logmcp

命令

命令	说明
logmcp serve	启动 MCP 服务（默认）
logmcp quickstart	无需配置文件即可立即启动（无需 root 权限）
logmcp setup	交互式设置向导
logmcp check	验证配置和环境
logmcp token list	列出已配置的 bearer 令牌
logmcp token add --name <n>	添加新的 bearer 令牌
logmcp token remove <name>	移除 bearer 令牌
logmcp token renew <name>	为现有令牌生成新值
logmcp logs list	列出可访问的日志文件
logmcp logs read <path>	读取日志文件或 journald://
logmcp logs search <path>	搜索日志文件或 journald://
logmcp logs info <path>	显示日志文件元数据
logmcp service install	安装 systemd 服务
logmcp service remove	移除 systemd 服务
logmcp service status	显示服务状态
logmcp service caddy-snippet	输出 Caddyfile 配置
logmcp client-config claude-code	输出 Claude Code MCP 配置
logmcp client-config vscode	输出 VS Code MCP 配置
logmcp client-config claude-desktop	输出 Claude Desktop MCP 配置
logmcp security install-fail2ban	为 logmcp 安装 fail2ban 过滤器和 jail

MCP 工具

以下是 LogMCP 向 AI 助手提供的工具：

工具	说明
list_logs	列出已配置为由服务公开的所有日志文件
read_log	读取日志文件中的行——文件头、文件尾、偏移量或时间范围
search_log	使用正则表达式搜索日志文件，可选上下文行和时间筛选
log_info	文件元数据：大小、行数、最后修改时间
check_environment	服务端运行状况检查（配置、TLS、白名单、syslog、数据库）
check_config	显示当前服务配置以及采用默认值的可选参数
server_status	MCP 层和已注册扩展的运行时状态

扩展可以添加更多工具——工具名称以扩展名为前缀（例如，名为 myapp 的扩展所提供的工具名为 myapp_status）。

扩展——将外部工具封装为 MCP 工具

LogMCP 可以将任何外部程序或服务作为额外的 MCP 工具公开——无需自定义 MCP 服务。AI 可以将它们与内置日志工具一并使用。

CLI 扩展

任何实现了 clitool interface（list / call 子命令）的程序都可以注册。LogMCP 会在启动时调用 <command> list 来发现工具，并将每次工具调用转发给 <command> call <tool> --token-stdin。

extensions:
  clitool:
    - name: myapp
      command: /usr/local/bin/myapp-ctl
      timeout_seconds: 10

每次调用都会启动一个子进程——适用于同一主机或远程主机上的任何程序。

RPC 扩展（Redis）

对于在同一主机上运行的程序，RPC 变体可以避免每次调用都启动进程的开销（对于 Python 程序来说，这一点很重要，因为解释器启动和导入会带来明显延迟）。LogMCP 不会启动子进程，而是将请求推送到 Redis 列表，并等待工作进程回复。

extensions:
  clitool:
    - name: myapp
      command: /usr/local/bin/myapp-ctl   # still used for `list` at startup
      mode: rpc
      redis_addr: "127.0.0.1:6379"
      timeout_seconds: 5

工作进程从 Redis 列表中读取请求，并将回复推送到每个请求对应的回复键。完整协议请参阅 docs/RPC.md。

身份验证流程

每个传入 MCP 请求中的 bearer 令牌都会转发给扩展——CLI 模式下通过 stdin 传递，RPC 模式下作为 RPC 信封中的 caller 元数据传递。扩展可以验证该令牌，也可以信任预先解析的身份。

---

案例研究

LogMCP 在真实场景中发挥作用的示例——请参阅 docs/case-studies.md：

• Asterisk/VoIP — 调试软件包编译和依赖项错误
• 使用 Caddy 反向代理的 Web 服务器 — 生产环境安装
• 使用自有 TLS 的独立运行模式

SSH 隧道设置

如果你在本地使用 Claude Code，并且已经可以通过 SSH 访问服务器，就可以在没有公共 HTTPS 端点的情况下运行 LogMCP：

# Forward remote port 7788 to localhost
ssh -L 7788:127.0.0.1:7788 user@yourserver

# Then point your MCP client at https://localhost:7788

LogMCP 仍要求通过隧道使用 bearer token——SSH 层提供传输安全性，令牌则控制哪些客户端可以连接。

许可证

MIT 许可证——请参阅 LICENSE。