Dozzle MCP 集成实战指南：让 AI 编程助手直接读取 Docker 容器日志与状态

Dozzle MCP 集成实战指南让 AI 编程助手直接读取 Docker 容器日志与状态【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzle本文以 Dozzle 官方 MCP 集成文档 为骨架结合仓库中internal/mcp的源码实现与测试用例系统讲解如何在 Dozzle 上开启 Model Context ProtocolMCP端点、接入 VS Code Copilot 或 Claude Desktop 等 AI 客户端以及五个只读工具的参数语义、返回结构与底层原理。读完本文你将掌握从启用端点到认证加固的完整落地方案并能基于源码理解工具的能力边界与性能行为。一、背景为什么 Dozzle 需要 MCPDozzle 是一个面向容器的实时日志查看器支持 Docker、Swarm 与 K8s。过去AI 编程助手在排查容器问题时只能靠人类把日志粘贴进对话而借助 MCPAI 客户端可以通过标准化的工具调用协议直接查询 Dozzle 持有的容器元数据、日志与性能数据实现让 AI 自己去看日志的排查闭环。Dozzle 对 MCP 的集成方式是内建原生端点启用后Dozzle 会在自身容器内暴露一个位于/api/mcp的 MCP 端点采用 Streamable HTTP 传输不需要额外进程或 sidecar 容器。这一设计让部署成本几乎为零只需一个开关。适用场景Docker本地守护进程与 Swarm 模式均可使用MCP 端点本身与宿主类型无关只要 Dozzle 能访问到容器数据AI 客户端就能通过工具读取。二、启用 MCP 端点MCP 功能默认关闭。开启方式有二启动参数--enable-mcp或环境变量DOZZLE_ENABLE_MCPtrue两者等价。该开关在源码中有明确记录参数定义 声明为arg:--enable-mcp,env:DOZZLE_ENABLE_MCP default:false随后在 main.go 中透传给 Web 层配置。2.1 使用 docker rundocker run --volume/var/run/docker.sock:/var/run/docker.sock -p 8080:8080 amir20/dozzle --enable-mcp2.2 使用 docker-composeservices: dozzle: image: amir20/dozzle:latest volumes: - /var/run/docker.sock:/var/run/docker.sock ports: - 8080:8080 environment: DOZZLE_ENABLE_MCP: true环境变量方式与全部启动参数的对应关系可在 supported-env-vars.md 中查到--enable-mcp对应DOZZLE_ENABLE_MCP默认值false。2.3 端点的路由注册从源码看MCP 端点并不是一个独立的监听端口而是挂在既有 HTTP 路由上。routes.go 在/api路由的认证保护组内完成挂载// MCP (Model Context Protocol) endpoint if h.config.EnableMCP { mcpServer : dozzle_mcp.NewServer(h.hostService, h.config.Labels, h.config.Version) r.Mount(/mcp, mcpServer.Handler()) }这意味着未启用时该端点根本不存在路由未注册对外不可见而非返回 404 页面启用后端点地址为/api/mcp若配置了自定义 base path如--base /dozzle端点自动变为/dozzle/api/mcp——路由挂载在base之下无需额外配置。三、可用工具五个只读工具全解析Dozzle 的 MCP 工具集共 5 个全部标记为ReadOnlyHint: true见 registerTools只读取数据、绝不修改容器因此可以安全地开放给 AI 助手。工具说明list_containers列出所有主机上的全部容器支持可选的state过滤get_container_logs获取结构化日志含日志级别检测、JSON 解析与多行分组search_container_logs按关键词/短语搜索容器日志仅返回匹配条目list_hosts列出所有已连接的 Docker 主机get_container_stats获取容器的 CPU 与内存使用历史这 5 个工具在 server_test.go 的TestNewServerRegistersTools中被验证为恰好 5 个且名称与上述表格一致。3.1 list_containers列出全部主机上的容器。参数只有一个参数类型说明statestring可选按容器状态过滤running、exited、created、paused、dead留空则返回全部返回的每条记录包含id、name、image、state、health如有、host、created、labels、group等元数据结构定义见 handleListContainers。实现细节server.go遍历所有主机汇总单台主机失败不会导致整体失败只记录partial failure警告日志state过滤是精确匹配容器当前状态测试用例TestListContainersserver_test.go验证了全量与state: running过滤两种场景TestListContainersPartialFailure验证了部分主机不可达时仍返回可用数据。3.2 get_container_logs获取指定容器的结构化日志。参数定义见 getContainerLogsParams参数类型说明hoststring必填容器所在主机的 ID可通过list_containers获取container_idstring必填容器 ID支持短 IDsince_minutesint可选取最近 N 分钟的日志默认 5streamstring可选读取哪个输出流stdout、stderr或all默认all返回的是换行分隔的 JSONNDJSON每条日志条目结构如下mcpLogEntry字段类型说明timestampstringRFC3339Nano 格式的 UTC 时间戳levelstring可选自动检测的日志级别error/warn/info/debug/trace/fatal 等streamstring可选来源流stdout/stderrtypestring日志类型single / group / complexmessageany消息内容多行分组时为字符串数组JSON 日志时为解析后的对象几个值得注意的行为多行分组连续的多行日志会被合并为一个type: group条目message为字符串数组见 eventMessageJSON 解析若日志行是 JSONtype会变为complexmessage为解析后的对象日志级别检测level由 Dozzle 的级别猜测器完成其实现位于 level_guesser.go按从高到低的置信度分 7 层匹配行首前缀、方括号标签、分隔符、大写词等内置error/err、warn/warning、info/inf、debug/dbg、trace/verbose、fatal/critical等别名映射stream参数非法时会返回invalid stream xxx: must be stdout, stderr, or all错误parseStream测试TestGetContainerLogsInvalidStream验证了这一点时间范围内无日志时返回(no logs in the specified time range)。3.3 search_container_logs在容器日志中搜索关键词只返回匹配条目——与直接拉全量日志再人工筛选相比可显著降低 AI 读取的数据量。参数searchContainerLogsParams参数类型说明hoststring必填主机 IDcontainer_idstring必填容器 ID支持短 IDquerystring必填要查找的搜索字符串默认不区分大小写since_minutesint可选搜索最近 N 分钟的日志默认 5streamstring可选搜索哪个流stdout、stderr、all默认allcase_sensitivebool可选是否区分大小写默认 false实现要点handleSearchContainerLogs匹配方式是子串包含strings.Contains对多行分组会把多条消息拼接后匹配返回格式为Found N matches for query (scanned M entries):后跟匹配的 NDJSON 条目无匹配时返回(no matches for query in M log entries scanned)结果超限时返回(results truncated at 1MB; narrow your query or time range to see more)。对应测试覆盖完整TestSearchContainerLogs 验证只返回匹配项并统计命中数TestSearchContainerLogsCaseSensitive验证大小写开关TestSearchContainerLogsNoMatches验证无命中提示TestSearchContainerLogsTruncates验证 1MB 截断行为。3.4 list_hosts列出所有已连接的 Docker 主机无需参数。返回字段handleListHosts字段说明id主机 IDname主机显示名nCPUCPU 核数memTotal总内存字节dockerVersionDocker 版本type主机类型如 local / agentavailable是否可用3.5 get_container_stats获取容器 CPU 与内存使用历史。参数getContainerStatsParamshost与container_id均为必填。返回结构handleGetContainerStats包含containerId、containerName、memoryLimitBytes、cpuLimit、dataPoints以及stats数组其中每个数据点含字段说明cpuPercentCPU 使用百分比memoryPercent内存使用百分比memoryUsageBytes内存使用量字节数据来自容器统计的环形缓冲约最近 5 分钟的历史窗口见测试 TestGetContainerStats。容器不存在时返回错误结果IsError: true。四、客户端配置接入 VS Code 与 Claude Desktop4.1 VS CodeGitHub Copilot / Copilot Chat将以下配置加入项目的.vscode/mcp.json或用户级 MCP 设置{ servers: { dozzle: { type: http, url: http://localhost:8080/api/mcp } } }4.2 Claude Desktop在 Claude Desktop 的 MCP 配置中加入{ mcpServers: { dozzle: { type: streamable-http, url: http://localhost:8080/api/mcp } } }[!NOTE] 请将localhost:8080替换为你 Dozzle 实例的实际地址。如果 Dozzle 配置了自定义 base path例如--base /dozzleMCP 端点将位于/dozzle/api/mcp。五、认证与安全MCP 端点归属已认证的 API 组前文路由代码可见它注册在RequireAuthentication中间件保护的路由组内。开启认证后MCP 客户端必须提供有效凭据。5.1 Simple Auth--auth-provider simple需要让 MCP 客户端在Authorization头中携带有效的 JWT token。获取 token 的步骤向/api/token发送POST请求携带用户名与密码对应 createToken 实现该路由在 routes.go 中注册于/api之下将返回的 token 作为 Bearer 头配置到 MCP 客户端。VS Code MCP 配置示例{ servers: { dozzle: { type: http, url: http://localhost:8080/api/mcp, headers: { Authorization: Bearer your-jwt-token } } } }需要生成users.yml用户文件时可使用 Dozzle 内置的generate子命令例如docker run -it --rm amir20/dozzle generate admin --password password --email testemail.net --name John Doe users.yml完整说明见 认证指南。5.2 Forward Proxy Auth--auth-provider forward-proxy认证由 Dozzle 前置的反向代理完成并注入头部。MCP 客户端应通过同一代理访问Dozzle认证将被透明处理无需在客户端配置额外凭据。注意此时不应直接暴露 Dozzle 端口详见 认证文档的安全注意事项。5.3 No Auth默认未配置任何认证提供者默认情况时MCP 端点公开可访问无需额外配置。5.4 安全提示所有 MCP 工具均为只读不会启动、停止、重建或执行容器内命令这是与 Dozzle 的 actions / shell 功能最本质的区别但 Dozzle 本身拥有docker.sock访问权若实例暴露在公网务必参考 认证文档 启用认证并限制访问在多用户 认证场景下MCP 读取会沿用请求用户的容器过滤规则源码中的 resolveLabels 会优先采用请求上下文中的用户过滤条件仅当无用户上下文如未开启认证时才回退到服务端全局标签过滤。测试 TestReadToolsUseRequestingUsersFilter 专门验证了受限用户不能透过全局过滤读取容器这一行为。六、源码级原理一次工具调用的完整链路以get_container_logs为例理解内部调用链有助于预判工具行为与性能边界解析参数handleGetContainerLogs首先校验host与container_id非空定位容器fetchLogs 通过FindContainer按主机 ID 查找容器服务并解析stream参数确定时间窗口since_minutes未传或小于等于 0 时使用默认值5 分钟窗口为[now-5m, now]读取日志调用LogsBetweenDates拉取事件流消费与编码collectLogEntries 逐条消费事件并编码为 JSON累计超过1MBmaxLogSize即停止并标记truncatedencodeLogEntries 输出 NDJSON 文本返回结果以纯文本形式封装在CallToolResult中返回给客户端。这个 1MB 上限是刻意设计的保护它保证了 AI 客户端收到的响应体有界避免超大日志拖垮对话上下文。如果你需要更完整的日志视图应通过缩小since_minutes或使用search_container_logs精确命中目标而不是试图一次拉全。七、实战建议排查首选搜索工具search_container_logs只返回匹配条目并报告扫描总数适合让 AI 定位报错关键词如error、panic、timeout信息密度远高于全量拉取缩小时间窗口since_minutes默认只有 5 分钟排查历史问题务必显式调大按流过滤服务端错误通常在stderr指定stream: stderr可减少一半噪音先列后取AI 不熟悉环境时先调用list_hostslist_containers确定主机 ID 与容器 ID再调用日志与统计工具结合 base path实例藏在子路径如/dozzle后时客户端 URL 记得补全为/dozzle/api/mcpSwarm/Docker 通用MCP 端点不区分 Swarm 或单机 Docker启用方式一致。参考资料官方文档MCP 集成、环境变量与子命令、认证指南核心实现MCP 服务端、路由注册、CLI 参数定义、日志级别检测测试证据MCP 服务端测试工具注册、参数校验、过滤作用域、1MB 截断等用例【免费下载链接】dozzleRealtime log viewer for containers. Supports Docker, Swarm and K8s.项目地址: https://gitcode.com/GitHub_Trending/do/dozzle创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考