h5-devtools-mcp
Enables debugging of H5 pages running inside Android WebViews on real devices over adb and the Chrome DevTools Protocol, without needing chrome://inspect. Provides tools to list debuggable WebView pages (with app package, title, URL, and visibility), attach to a page and buffer console output, read console messages and uncaught exceptions incrementally with level/keyword filtering, evaluate JavaScript expressions in the page, and detach from a page.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@h5-devtools-mcp list debuggable WebViews, then show me recent console errors on the order page"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
h5-devtools-mcp
English | 简体中文
An MCP server that lets coding agents (Claude Code, Codex, Cursor…) debug H5 pages running inside Android WebViews on real devices — read console output and uncaught exceptions, and run JavaScript in the page, without opening chrome://inspect.
Status: v0.1, early. Android only.
How it works
Coding agent ──MCP (stdio)──▶ h5-devtools-mcp ──adb forward──▶ webview_devtools_remote_<pid> ──CDP──▶ WebView pageEvery debuggable WebView exposes a Chrome DevTools Protocol endpoint on an abstract unix socket. The server discovers those sockets over adb (the same way chrome://inspect does), forwards them to local ports, and connects with CDP.
Related MCP server: Debug Web MCP
Requirements
Node.js 18+
adbon yourPATH(or setADB_PATH)An Android device with USB debugging enabled
The app must enable WebView debugging (debug builds usually do):
WebView.setWebContentsDebuggingEnabled(true);Setup
# Claude Code
claude mcp add h5-devtools -- npx -y h5-devtools-mcpOther MCP clients (Cursor, Codex…) take the same command: npx -y h5-devtools-mcp.
From source
git clone https://github.com/xianguoGou/h5-devtools-mcp.git
cd h5-devtools-mcp
npm install && npm run build
claude mcp add h5-devtools -- node /absolute/path/to/h5-devtools-mcp/dist/index.jsTools
Tool | What it does |
| List debuggable pages: app package, title, URL, visibility |
| Connect to a page and start buffering console output |
| Read buffered entries, filtered by level / keyword / |
| Run a JavaScript expression in the page and return the result (promises are awaited) |
| Disconnect from a page |
Output is designed to be token-cheap: compact one-line entries, long messages truncated, and since_seq so an agent only reads what's new instead of re-reading the whole buffer on every turn.
Example
> list_targets
- id: R5CT1234/webview_devtools_remote_8812/3A1F…
app: com.example.app (pid 8812) on SM-S9180
title: "Order"
url: https://m.example.com/order
> get_console { "levels": ["error"] }
#41 10:32:01.123 [error exception] TypeError: Cannot read properties of undefined (reading 'price')
at https://m.example.com/assets/index-8f2a.js:1:48213
next since_seq: 57Troubleshooting
"no debuggable WebView found" — the app hasn't enabled WebView debugging, or no WebView is alive yet. Open the H5 page first.
"debugger in use" — only one debugger can attach to a page. Close the
chrome://inspectDevTools window."unauthorized" — accept the USB debugging prompt on the device.
Known limitations
Debugger-in-use detection is best-effort. It relies on
/json/listomittingwebSocketDebuggerUrl. Recent Chromium accepts several CDP clients per page, so attach may succeed alongside an open DevTools window; older WebViews may still refuse.list_targetscan take ~3s per unresponsive app. Sockets are queried one by one with a 3s timeout, and Android freezes background apps, so their WebView sockets stop answering.attachonly re-checks the target's own socket and stays fast.evaluate_jsruns with the page's full privileges — it can read cookies, storage and tokens, and change page state. Keep it behind your agent's tool-permission prompt.The e2e script expects port 9333 to be free. If a previous run left a headless Chromium behind, it attaches to that one; kill it first.
Development
The e2e test uses a fake adb and headless Chromium in place of a phone:
npm run build
CHROME=/path/to/chrome npm run test:e2eRoadmap
Discover devices and WebView pages
Console messages, uncaught exceptions, browser log entries
Network requests and responses
JSBridge call logging (configurable bridge shapes)
evaluate_jsscreenshotJSBridge mocking
iOS (WKWebView via WebKit Inspector Protocol)
License
MIT
Available Tools
5 toolsattachAttach to a pageA
Connect to a WebView page and start buffering its console output and uncaught exceptions. Recent messages the engine still holds are replayed on attach, but attach before reproducing an issue to be sure nothing is missed.
Inputs: target_id (required).
detachDetach from a pageA
Disconnect from a page and discard its buffered events.
Inputs: target_id.
evaluate_jsEvaluate JavaScript in a pageADestructive
Run a JavaScript expression in an attached page and return its result. Plain objects/arrays come back as JSON (so nested Map/Set/DOM values show as {}); other values (DOM nodes, Map, Set, Error, window) as a short description. Promises are awaited. For multiple statements or await, wrap them: (async () => { ... })(). Runs with the page's full privileges, so it can read cookies/storage and change page state.
Inputs: expression (required), target_id.
get_consoleRead console outputARead-only
Read buffered console messages, uncaught exceptions and browser log entries from an attached page. Returns the most recent matching entries. Pass since_seq from a previous call to get only new entries.
Inputs: limit, levels, keyword, since_seq, +2 more.
list_targetsList WebView pagesARead-only
List debuggable H5 pages running inside Android WebViews (and Chrome) on connected devices. Returns a target id for each page to pass to attach.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool maps to a distinct step in the debug session: list_targets discovers pages, attach connects, get_console reads buffered logs, evaluate_js executes code, and detach disconnects. There is no meaningful overlap between any pair; an agent can select unambiguously.
The dominant pattern is verb_noun (list_targets, get_console, evaluate_js), which is clean and readable. attach and detach are bare verbs, a minor but explainable deviation since their object is implied by the session model.
Five tools is exactly right for a focused WebView debugging workflow — one per lifecycle stage with no filler. Nothing feels padded or missing at the count level.
The full core loop (discover, attach, observe console, evaluate JS, detach) is covered, including sequence-based log polling, so agents won't hit dead ends. Secondary debugging surfaces like network inspection, screenshots, or device-level listing are absent but not essential to the stated purpose.
Related MCP Connectors
remote debug iOS/Android/Unity/Godot/Flutter/RN/Web on real-device.ui-tree/screenshots/taps,tests.
Build, run, inspect, and continue AgentScript workflows on connected Super Chrome and Mac clients.
Drive real devices from your AI Coding tool. Embed a client SDK (Unity, Godot, Flutter, iOS/macOS, Android, React Native, Web) in your app, then capture screenshots, traverse the UI tree, inject taps and key events, and run automated test tasks on the physical device over a secure relay.
Give your AI agent a real cloud Android phone: push APKs, drive it, get screenshots and logs.
Related MCP Servers
- AlicenseAqualityBmaintenanceEnables debugging Flutter apps on Android by exposing the widget tree and source locations, supporting hot reload and pixel-level UI diffs, along with filtered Android logs, crash traces, and device interaction.26MIT
- AlicenseBqualityBmaintenanceEnables agents to inspect localhost web applications through Chrome DevTools Protocol by listing Chrome targets, attaching to a page, capturing and querying network, console, navigation, and WebSocket events, and managing ephemeral sessions.81MIT
- AlicenseNot gradedqualityBmaintenanceEnables agents to observe and act on live browser pages through screenshots, bounded actions, responsive captures, console and network inspection, tab operations, and session management over local stdio or authenticated HTTP.Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables debugging web pages in Chrome through a stdio MCP interface, including performance traces, network and console inspection, snapshots, screenshots, emulation, and page input by element UID.79 npmMIT