H5 Devtools Mcp

io.github.xianguoGouPublished by GitHub account xianguoGouv0.1.2Updated Nov 4, 2026

Debug H5 pages inside Android app WebViews: console logs, exceptions, run JS.

VerifiedSTDIODesktop onlyBrowser AutomationDeveloper Tools

Overview

AI-generated overview

Lets a coding agent debug H5 pages inside Android WebViews on real devices: list pages, read console logs and exceptions, and run JavaScript.

What you can do
  • List debuggable H5 pages in Android WebViews and Chrome on connected devices, with app package, title, URL and visibility
  • Attach to a page and start buffering its console output and uncaught exceptions
  • Read buffered console and exception entries, filtered by level or keyword and fetched incrementally
  • Run a JavaScript expression in the attached page and get the result back, with promises awaited
  • Detach from a page to stop capturing and clear the buffer
When to use it
Useful when debugging a web page embedded in an Android app and you want an agent to inspect logs, exceptions or page state without opening chrome://inspect. Best for mobile web debugging on a physical device during development.
Requirements
Runs locally over stdio via npx. Needs Node.js 18+, adb on PATH (or ADB_PATH set), an Android device with USB debugging enabled, and an app that enables WebView debugging. USB debugging authorization must be accepted on the device.
Before you install
evaluate_js runs with the page's full privileges, so it can read cookies, storage and tokens and change page state; keep it behind the agent's tool-permission prompt. Only one debugger can usually attach to a page, so close open DevTools windows. Early v0.1 release, Android only.

Installation

In SourceWeft

  1. Open H5 Devtools Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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.

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):
java
WebView.setWebContentsDebuggingEnabled(true);

Setup

bash
# Claude Codeclaude 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

bash
git clone https://github.com/xianguoGou/h5-devtools-mcp.gitcd h5-devtools-mcpnpm install && npm run buildclaude mcp add h5-devtools -- node /absolute/path/to/h5-devtools-mcp/dist/index.js

Tools

ToolWhat it does
list_targetsList debuggable pages: app package, title, URL, visibility
attachConnect to a page and start buffering console output
get_consoleRead buffered entries, filtered by level / keyword / exclude_keywords, incrementally via since_seq
evaluate_jsRun a JavaScript expression in the page and return the result (promises are awaited)
detachDisconnect 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:48213next 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:

bash
npm run buildCHROME=/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

Source: README.md at commit ce0e832

Tools

5

list_targets

List WebView pages

List debuggable H5 pages running inside Android WebViews (and Chrome) on connected devices. Returns a target id for each page to pass to attach.

Takes no parameters.

attach

Attach to a page

Connect to a WebView page and start buffering its console output and uncaught exceptions (the last 1000 entries). Recent messages the engine still holds are replayed on attach, but attach before reproducing an issue to be sure nothing is missed. Only observes the page: it is not reloaded or modified. May be refused while Chrome DevTools (chrome://inspect) is attached to the same page; close it and retry. Calling it again for an attached page reuses the existing session.

Parameterstarget_idrequired

get_console

Read console output

Read buffered console messages, uncaught exceptions and browser log entries from an attached page. Requires attach first; only entries captured since attach (plus what attach replayed) are available. Returns the most recent matching entries. Pass since_seq from a previous call to get only new entries.

Parameterslimitlevelskeywordsince_seqtarget_idexclude_keywords

evaluate_js

Evaluate JavaScript in a page

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.

Parameterstarget_idexpressionrequired

detach

Detach from a page

Disconnect from a page and discard its buffered console entries. The page itself keeps running and is not closed; call attach again to resume capturing. Use it to stop capturing or to start over with an empty buffer.

Parameterstarget_id

Version history

2
  1. v0.1.2LatestOct 21, 2026
  2. v0.1.1Oct 21, 2026

Score

90% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts
  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listedRequired15 pts
  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts