项目目标：docs/GOALS.md ·变更与升级说明：CHANGELOG.md ·贡献者/代理指南：AGENTS.md ·术语：docs/glossary.md

一个MCP（模型上下文协议）stdio服务器，为AI编码代理（如Claude Code、Codex CLI、Cursor等MCP主机）只读访问Android日志。它从不清除日志，从不启动或停止应用（除了report --am-start，只有在你请求时才会），也从不更改设备设置。

• 使用时开始的后台录制。 每个用户只需一个服务进程将设备记录到磁盘，因此历史记录能在重启和新会话中保持。设备从首次使用日志工具调用开始记录，从日志缓冲区回填，直到该设备在剩余时间内未被使用;android-log-mcp record --for 2h 在无调用的情况下继续录音。
• Android Studio 滤波器语法（tag: message~: -package: level: age: is:crash | &，括号内）带有严格错误：解析错误会给出列和修正，而不是默默降级为子串匹配，且每个响应都会先回应过滤器的解析方式。

android-log-mcp

Project goals: docs/GOALS.md · Changes and upgrade notes: CHANGELOG.md · Contributor / agent guidelines: AGENTS.md · Terms: docs/glossary.md

An MCP (Model Context Protocol) stdio server that gives AI coding agents (MCP hosts such as Claude Code, Codex CLI, Cursor, …) read-only access to Android logcat. It never clears logs, never starts or stops apps (except report --am-start, only when you ask) and never changes device settings.

• Background recording that starts on use. One service process per user records devices to disk, so history survives restarts and new sessions. A device is recorded from the first log tool call that uses it, backfilled from its log buffer, and until it has gone unused for the linger time; android-log-mcp record --for 2h keeps recording without calls.
• Android Studio filter syntax (tag: message~: -package: level: age: is:crash | &, parentheses) with strict errors: a parse error gives the column and a fix instead of silently degrading to a substring match, and every response first echoes how the filter was parsed.
• Crashes and ANRs (Java, native/tombstone, ANR) grouped by signature, with ANR traces and tombstones from dumpsys dropbox where available.
• App launch timelines (COLD / WARM / HOT, TTID / TTFD) from START u0, am_proc_start, am_on_*_called (API ≤ 29) / wm_on_*_called (API ≥ 30), Displayed and Fully drawn.
• Log export: logcat_export / android-log-mcp export write the matching lines to a text file for a human to read (unredacted unless asked; docs/reference.md).
• Diagnostic reports: android-log-mcp report packs logs and diagnostics into a zip with sensitive data redacted by default.

Prebuilt binaries for Linux, macOS and Windows (x64, arm64). Requires adb.

中文摘要： android-log-mcp 是一个 MCP stdio server，让 AI agent（MCP 宿主，如 Claude Code / Codex / Cursor 等）只读地访问 Android logcat：不清空日志、不启动或停止应用（report --am-start 除外，且只在你明确要求时）、不改设备设置。 安装：npx -y android-log-mcp（Windows 推荐原生二进制）。工具说明见 docs/tools.md，服务进程、数据与环境变量见 docs/reference.md，兼容性见 docs/compatibility.md，升级说明只在 CHANGELOG.md。

Install and configure

Prerequisites: adb (Android SDK platform-tools); Node.js ≥ 16 for npx (not needed for the native binary). Windows needs Windows 10 1803 / Windows Server 2019 or later. Go is not needed. adb is found via ANDROID_LOG_MCP_ADB, then PATH, then the usual SDK locations. Details, both install paths and the upgrade procedure: docs/reference.md.

A. npx (recommended on macOS and Linux)

npx -y android-log-mcp --version                 # check that it runs
npx -y android-log-mcp call logcat_status '{}'   # debugging: call one tool and print the result

macOS / Linux