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