Skip to main content
Glama

h5-devtools-mcp

npm version npm downloads license

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 page

Every 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+

  • adb on your PATH (or set ADB_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-mcp

Other 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.js

Tools

Tool

What it does

list_targets

List debuggable pages: app package, title, URL, visibility

attach

Connect to a page and start buffering console output

get_console

Read buffered entries, filtered by level / keyword / exclude_keywords, incrementally via since_seq

evaluate_js

Run a JavaScript expression in the page and return the result (promises are awaited)

detach

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: 57

Troubleshooting

  • "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://inspect DevTools window.

  • "unauthorized" — accept the USB debugging prompt on the device.

Known limitations

  • Debugger-in-use detection is best-effort. It relies on /json/list omitting webSocketDebuggerUrl. Recent Chromium accepts several CDP clients per page, so attach may succeed alongside an open DevTools window; older WebViews may still refuse.

  • list_targets can 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. attach only re-checks the target's own socket and stays fast.

  • evaluate_js runs 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:e2e

Roadmap

  • Discover devices and WebView pages

  • Console messages, uncaught exceptions, browser log entries

  • Network requests and responses

  • JSBridge call logging (configurable bridge shapes)

  • evaluate_js

  • screenshot

  • JSBridge mocking

  • iOS (WKWebView via WebKit Inspector Protocol)

License

MIT

Available Tools

5 tools
attachAttach 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 pageA
Destructive

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 outputA
Read-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 pagesA
Read-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

    A4.1/5.0

    Scored across 5 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      26
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      8
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 npm
      MIT