web-debug MCP server
Commit Oct 15, 2026Enables AI clients to reproduce, inspect, and verify web bugs by capturing browser runtime state, console logs, and network evidence.
Also known as MarlonJD/web-debug-mcp
- Stars
- 6
- Tools
- —
- Downloads, 30 days
- —
- Latest version
- —
- Last commit
- Oct 15, 2026
- License
- —
What is web-debug MCP?
web-debug enables AI clients to reproduce, inspect, and verify web bugs by capturing browser runtime state, console logs, and network evidence.
Summary generated from the project's README
About web-debug MCP server
Reproducing and verifying web application bugs from within an AI client is the primary function of web-debug-mcp. This local MCP server provides developers with a structured way to capture browser runtime state, console logs, and network evidence to diagnose frontend issues. It works over stdio and runs locally on your machine, meaning it does not require a hosted service to operate.
Users can integrate this server into Codex or Claude Code using the provided plugin or by installing the standalone npm package via npx. The toolset includes 13 specific tools designed to handle tasks like project detection, browser actions, and issue capture. It is specifically built to inspect framework-specific data, such as React state, Vue 3 component updates, and Next.js server actions, providing grounded evidence that standard test runners might miss.
By using tools like web_issue_capture and web_session_start, an AI agent can move from initial bug diagnosis to verifying a fix through a recorded replay of the browser flow. This creates a bounded workflow for debugging DOM, network, or JavaScript-debugger issues directly through the MCP interface.
What you can do with it
- 1Reproduce local frontend bugsAsk the AI to reproduce a specific React or Vue bug and capture the necessary browser evidence.
- 2Inspect framework runtime stateUse the server to understand React state, commits, or Vue 3 component props and state updates.
- 3Verify fixes with browser replaysHave the agent replay a browser flow to ensure a frontend fix actually works as intended.
- 4Diagnose network and console errorsCapture detailed evidence from the browser console and network tab to debug web issues.
Written from the project's README. Every use case is checked against a quote from it.
Configuration
WEB_DEBUG_CHROME_EXECUTABLE_PATH
Automated checks
Ran Nov 15, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablemarlonjd/web-debug-mcp is public and reachablegithub.com/marlonjd/web-debug-mcp ↗Pass
- Package names this repository as its sourceNot checked
- Build provenance (Sigstore attestation)Not checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2026-10-15github.com/marlonjd/web-debug-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNot checked
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubweb-debug-mcp
An evidence-first, local MCP debugger for web applications.
web-debug-mcp gives Codex and other MCP clients one bounded workflow for reproducing a web issue, inspecting browser and framework runtime state, collecting redacted evidence, and verifying the same flow after a fix. It covers the browser, frontend runtime, dev server, and replay timeline through one small MCP surface.
Release 0.13.0 adds compact verification with retained evidence resources, typed geometry/numeric/network checks, observable completion, safer API guidance and project logs, and grounded framework recovery. It preserves original-source diagnostics, native Safari console collection, interactive UI capture and direct WebMCP; the MCP catalog remains 13 tools.
Release 0.10.0 introduced selective capture and freshness states, tighter browser-routing guidance, stronger evaluation evidence, and Google Antigravity plugin compatibility.
Release 0.8.0 introduced identity-safe MCP startup recovery, bounded stale registry/sidecar reconciliation, schema-versioned doctor binding diagnostics, and a fail-closed Web Debug Gate 0 that never substitutes another browser runner when the requested MCP binding is unavailable.
Install as an MCP server
The core package is a standalone MCP server. The repository also includes an optional Web Debug plugin for Codex and ChatGPT: the MCP server provides callable debugging tools, while the bundled skill provides workflow guidance. Claude Code and other MCP clients can continue using the standalone server.
The published npm package runs locally over stdio and does not require a hosted service.
Codex CLI, desktop app, and IDE extension
From a terminal:
codex mcp add web-debug-mcp -- npx -y web-debug-mcp@0.13.0
codex mcp list
The Codex desktop app and IDE extension share the same MCP configuration. You can also open Settings → MCP servers → Add server, choose STDIO, use npx as the command, and add these arguments:
-y web-debug-mcp@0.13.0
For a project-scoped Codex configuration, add this to ~/.codex/config.toml or a trusted project .codex/config.toml:
[mcp_servers.web_debug_mcp]
command = "npx"
args = ["-y", "web-debug-mcp@0.13.0"]
startup_timeout_sec = 20
tool_timeout_sec = 150
# Optional strict host policy: fail startup if this server cannot initialize.
required = true
Verify the connection with codex mcp list. In the Codex TUI, /mcp shows the active server.
MCP startup and binding recovery
A request for live Web Debug execution is fail-closed: the bundled web_project_detect call is Gate 0. A doctor pass, a process visible in a terminal, or a loaded skill does not prove that the current Codex task has the Web Debug tool namespace. If Gate 0 is unavailable, report MCP_CLIENT_BINDING_UNAVAILABLE (or MCP_SERVER_STARTUP_UNAVAILABLE when the server reports a startup failure) and stop that browser route; continue independent authorized source work. Do not substitute Playwright, Puppeteer, raw CDP, a direct MCP SDK client, a naked npx web-debug-mcp process, or web-debug-mcp cleanup.
The plugin-bundled .mcp.json intentionally contains only the supported launch command and timeouts. Codex currently documents required = true for a direct [mcp_servers.<name>] entry in config.toml, not for a plugin manifest field. To apply the strict policy, configure the direct server entry above and disable the duplicate plugin-provided server in the user plugin policy:
[plugins."web-debug@web-debug".mcp_servers.web-debug-mcp]
enabled = false
If the server is missing from the current task after a repair, use Codex Settings → MCP servers → Restart (or restart the IDE extension), then retry Gate 0. A new task/session is the supported recovery when the current task does not refresh its tool binding. Codex CLI 0.152.0 or newer is the supported host baseline; 0.151.0 adds optional-MCP discovery grace, while older hosts are candidate-only for this recovery contract. See the Codex MCP configuration and Codex changelog.
Use Web Debug as a plugin
This is the recommended single-install path for Codex and Claude Code. Installing Web Debug installs both workflow skills and the web-debug-mcp MCP server connection. It is not a skill-only package, and no separate MCP setup is required.
The same plugin package supports both Codex and Claude Code. Codex reads the Codex plugin manifest, Claude Code reads the Claude Code plugin manifest, and both use the same workflow skills and MCP configuration.
The plugin contains five pieces:
- the web-debug plugin manifest;
- the web-debug-workflow skill, which owns isolated browser-bug reproduction and fix verification;
- the manual-parity-qualification skill, which maps reviewed manual/product requirements to repository-native qualification tests and non-executable crosswalk/run metadata;
- the webmcp-tool-authoring skill, which provides authority-gated, direct-only WebMCP product guidance;
- a bundled .mcp.json connection that starts the existing web-debug-mcp server.
The runtime flow is:
install Web Debug plugin
↓
Codex loads all three skills and the bundled MCP connection
↓
bug diagnosis → Codex starts web-debug-mcp over local stdio on demand
↓
web_project_detect → reproduce → web_issue_capture → fix verification
manual parity → reviewed baseline → native Playwright/API tests
↓
crosswalk/run validation → Web Debug only if browser diagnosis is needed
The stdio binary also exposes two package-only commands. web-debug-mcp doctor checks the exact project, explicit browser configuration, protocol-shaped CDP endpoints, optional loopback URL, local Safari driver availability, and detected Vite/Next readiness without launching an arbitrary browser. An executable-path result validates configuration only and remains a warning until a real session launches. web-debug-mcp cleanup [--all-idle] emits a bounded JSON report and signals only idle, owner-only registry records whose process identity is revalidated; it never scans or signals unregistered browser/debug processes.
Install from the Codex CLI
Add this repository’s marketplace, then install the web-debug plugin:
codex plugin marketplace add MarlonJD/web-debug-mcp --ref main
codex plugin list --available --marketplace web-debug
codex plugin add web-debug@web-debug
Install from the Codex desktop app
Run the marketplace command above once, open the Plugins Directory, refresh it if necessary, and install or enable Web Debug. Then start a new thread so the plugin’s skill and MCP tools are loaded.
Use the installed plugin
-
Start your local web application.
-
Ask Codex either to reproduce a browser issue or to build reviewed manual-parity qualification, for example: “Reproduce this local React bug and capture browser evidence” or “Turn these approved manual cases into a qualification crosswalk and native Playwright coverage.”
-
The plugin routes isolated bugs through project detection, an explicit local browser session, bounded actions, evidence capture, and recorded-flow fix verification. It routes qualification through reviewed requirements, repository-native tests, structural crosswalk/run validation, and diagnostic-only Web Debug escalation.
-
For live Chromium launch, provide an explicit executable path, for example:
WEB_DEBUG_CHROME_EXECUTABLE_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome" codex -
Close the session with web_session_close when debugging is complete.
The plugin runs the same local server as the standalone MCP install. It does not host a browser, upload evidence, or create a second tool catalog. The first MCP start uses npx to resolve the immutable web-debug-mcp@0.13.0 npm release; Node.js 20+, npm, and network access are required.
Boundary with Build Web Apps and native runners
Web Debug complements rather than replaces frontend build and test tooling:
- Build Web Apps owns frontend authoring, dev-server work, generic rendered QA, and visual implementation.
- Vitest, Go, and a project’s own Playwright commands own deterministic runner evidence.
- Web Debug owns local browser-grounded evidence: live DOM/console/network state, CDP and framework diagnostics, semantic probes, replay, and bounded fix verification.
- Manual Parity Qualification owns source/reviewer state, requirement-to-test crosswalks, mutation certainty, and truthful aggregate reporting around those native runners.
When a request explicitly names Web Debug, use the Web Debug workflow. For mixed work, establish an exact runner failure first, collect only the missing browser evidence with Web Debug, and rerun the relevant checks separately.
When approved manual cases do not exist, Manual Parity Qualification can derive source-linked candidate cases from product requirements, role matrices, state models, API contracts, existing tests, and exploration. Generated candidates never self-approve or become gating coverage. JSON is non-executable metadata only; selectors, browser actions, API calls, and assertions remain typed native test code. The bundled read-only validator checks reference closure, crosswalk completeness, evidence facets, mutation certainty, and aggregate arithmetic without authenticating reviewers or running tests.
Do not install both the plugin and a separate Codex or Claude Code MCP registration for web-debug-mcp unless you intentionally want duplicate MCP registrations. For other MCP clients, use the standalone MCP installation below.
Install in Claude Code
Add the repository marketplace from a Claude Code session, then install the plugin:
/plugin marketplace add MarlonJD/web-debug-mcp
/plugin install web-debug@web-debug
/reload-plugins
Choose the desired installation scope when Claude Code opens the plugin details. If the install summary says the plugin is already active, no reload is needed. The plugin’s MCP server starts automatically when the plugin is enabled, and its tools appear in /mcp. The bundled workflows can also be invoked directly as /web-debug:web-debug-workflow and /web-debug:manual-parity-qualification.
For local development or testing before publishing the repository, load the plugin directly:
claude --plugin-dir ./plugins/web-debug
This command loads the repository's plugin metadata, all three skills, and bundled web-debug-mcp@0.13.0 runtime.
Use the standalone MCP server in Claude Code
Install it for all projects on the machine:
claude mcp add --transport stdio --scope user web-debug-mcp -- npx -y web-debug-mcp@0.13.0
claude mcp list
For the current project only, use --scope project instead of --scope user; Claude Code writes the shared configuration to .mcp.json and asks for project approval. Use /mcp inside Claude Code to inspect the connected server and its tools.
To follow the latest npm release instead of the pinned command above, use npx -y web-debug-mcp.
When the agent should use it
Use it when a local web application is running and the task needs browser-grounded evidence, such as:
- reproducing a DOM, console, network, screenshot, or JavaScript-debugger issue;
- understanding React state, commits, render causes, or bounded flamegraph data;
- inspecting bounded Angular development component/state changes through documented debug globals;
- inspecting bounded Vue 3 development component/props/state updates through a safely chained DevTools hook;
- investigating Vite module/HMR/transform behavior;
- inspecting Next.js routes, logs, request traces, or Server Actions;
- replaying and verifying a browser flow after a frontend fix.
Start with web_project_detect, then use web_session_start, web_browser_action, and web_issue_capture. Use web_next_inspect for Next-specific inspection and web_repro_record plus web_fix_verify for regression verification.
Do not use this server for native macOS/iOS build-debug work, production monitoring, arbitrary remote browser control, credentialed browser profiles, or application-state time travel. Those are outside this MCP's contract.
Official setup references: Codex MCP configuration, Codex plugin packaging, and Claude Code MCP configuration.
Why this project exists
Web debugging is usually split across several disconnected surfaces:
- browser DevTools for DOM, console, network, screenshots, and JavaScript pauses;
- React or framework tooling for component state and render behavior;
- Vite or Next development servers for transforms, routes, logs, traces, and Server Actions;
- a human-written reproduction that is often difficult to repeat after a change.
An agent can edit code without having a reliable, structured account of what happened in the running app. web-debug-mcp closes that gap. It turns a reproduction into bounded evidence that an agent can inspect, compare, and use for fix verification.
The project deliberately keeps one public MCP catalog. React, Angular, Vue, Vite, Next, Chromium, and Safari are internal adapters behind the same session and evidence contract, so adding framework context does not create overlapping MCP servers.
What MCP adds here
MCP is the transport and tool contract between an agent such as Codex and this debugging process. The server exposes typed, discoverable operations instead of asking the agent to parse terminal output or drive an unstructured DevTools UI.
The public tools cover:
- project capability detection;
- explicit Chromium or Safari session start and status;
- bounded browser actions: navigate, click, fill, exact-locator probe waits, and reload;
- deterministic locator actions for keyboard press, select, checked state, hover, and scroll-into-view;
- issue capture with compact summary (default), explicit full evidence, selected surfaces, or cursor-based changed surfaces;
- Chromium breakpoints, pause control, and guarded JavaScript evaluation;
- Next route compilation and Server Action lookup;
- replay frame inspection and safe-action restore;
- reproducible flow recording and post-change verification;
- session cleanup.
Every tool advertises and enforces its own concrete MCP data schema. Repeated structures use SDK-supported local JSON Schema definitions and references; this reduces catalog bytes while preserving runtime validation. Each tool returns its result inside one canonical { ok, data, error, artifacts, warnings } structured envelope. Stable top-level and capture-profile fields are concrete; bounded deep runtime/upstream payloads such as evaluation values, debugger locals, framework trees, and Next metadata remain JSON leaves. Text content is only a bounded preview. Requests rejected by the MCP SDK before handler dispatch use the SDK protocol-validation error shape and have no tool structuredContent. Screenshot pixels are inlined only when small enough for the result budget; every accepted screenshot also receives a non-enumerable, identity-revalidated web-debug://artifact/... resource link. Screenshot retention is capped at 4 MiB per file and four files/16 MiB per session; quota pruning can expire an older resource before its one-hour maximum TTL. Long baseline and post-fix operations emit monotonic MCP progress when the client requests it.
Source and execution diagnostics
The local source checkout adds original-source breakpoints, bounded source inventories, opt-in execution coverage and request initiators, and explanatory capture/verification differences. These additions are included in 0.12.0.
Use web_issue_capture with view: { profile: "include", surfaces: ["sources"] } to discover exact source URLs and script IDs. Pass coordinateSpace: "original" to web_breakpoint_set to map one-based original coordinates into the selected script. Missing or ambiguous maps remain explicit; replacement scripts require a new breakpoint.
For a short diagnostic window, add diagnostics: { coverage: true, settleMs: 250 } to web_browser_action. The result includes observed ranges, source locations, request initiators, and available React commit counts. Coverage changes JIT/timing and remains off by default; fix verification runs without it. Associations with the action are temporal, not proof of causality. Safari rejects this diagnostic option before acting.
Capture deltas and web_fix_verify include bounded differences that explain errors, requests, React changes, and available execution changes. The existing verification checks remain authoritative. See the diagnostic contract for coordinates, scope, limits, privacy, and cleanup, and run npm run smoke:source-correlation for the minified TSX workflow.
Capture profiles
web_issue_capture defaults to { "view": { "profile": "summary" } }. Summary returns a compact DOM excerpt, counts, latest failures, runtime presence, replay bounds, warnings, and a reusable opaque cursor without producing screenshot pixels. Summary collects base browser observations but skips optional React/Angular/Vue, Next/Vite, accessibility, interactive-element, and WebMCP inspection. Use an explicit profile when more detail is necessary:
full: every bounded surface plus an explicit screenshot attempt;include: only the unique namedsurfaces; includescreenshotto opt into pixels;delta: the current bounded values of selected surfaces whose digest changed sincecursor; omittedsurfacesmeans every evidence surface except replay and screenshot, whose capture side effects require explicit inclusion. This is not JSON Patch, an event stream, or browser-state time travel. Requested screenshots use a fresh artifact rather than pixel diffing, so each successfully captured screenshot is changed.
Surfaces are dom, console, network, debugger, react, angular, vue, next, vite, accessibility, interactiveElements, webmcp, replay, screenshot, and serverLogs. Capture schema 6 reports a collection state for each: fresh, stale, not-collected, not-detected, unavailable, or suppressed. Skipped collection is not absence: the callable WebMCP count is null until metadata is collected. Included framework evidence is collected only for detected, supported runtimes; paused cached values are stale. interactiveElements is an explicit, bounded visible-action map: it carries names/text, an existing locator, live match count/uniqueness, enabled/checked state, and viewport geometry, but never input values. Chromium live-validates the emitted locator; Safari emits CSS locators derived from stable id/data-testid attributes and keeps semantic locator capability unavailable. A cursor remembers only its own collected surfaces, so an explicit later collection is changed relative to a summary that skipped it, even if an older capture saw the same value. Each session retains at most eight reusable cursors. Unknown, evicted, cross-session, or browser-generation-stale cursors fail explicitly. Screenshot paths never appear in capture data; accepted pixels are delivered only through the envelope's artifact descriptors. Scenario baseline and fix verification still retain authoritative full evidence independently of the manual profile.
Compact verification output in 0.13.0
Release 0.13.0 returns scenario/verification summary schema 7 from web_repro_record and web_fix_verify. All authoritative checks, repetition/isolation facts and full collection still run. The response keeps check outcomes, missing evidence, differences and immutable observation references; it does not repeat scenario actions or full runtime bundles. The plugin runtime is pinned to the same 0.13.0 release. Clients consuming the former full scenario/verification payload must use the summary and read its evidence references when full observations are needed.
Read a reference without rerunning browser actions by passing this to web_issue_capture:
{"sessionId":"<live-session-id>","view":{"profile":"recorded","evidenceRef":"web-debug://evidence/<opaque-id>"}}
The same opaque reference is an unlisted MCP JSON resource. Recorded evidence reports capture time/attempt and SHA-256; freshness describes the original observation, not the current page. Records are capped at 96 KiB, eight per live session and 64 per process, with a one-hour maximum lifetime. Close and subsequent private fill/select/WebMCP operations invalidate JSON references. Verification screenshots remain separate resources and are never inlined in compact responses. Missing, evicted, expired and wrong-session references return EVIDENCE_NOT_FOUND.
Recorded checks now also include locatorInViewport (the entire visible rectangle), locatorUnobstructed (a center hit test), locatorNumber (finite decimal DOM text with explicit tolerance), networkResponse (all matching same-origin method/path responses have the declared status), and networkComplete (actual transport completion, independent of HTTP success). Missing telemetry, stale observations, ambiguous locators and truncated network history remain unavailable; localized/currency strings are not silently parsed.
For async flows, declare completion: { checks, timeoutMs, stableForMs } using observations independent of the bug's acceptance condition, such as completion of the relevant request. Each attempt retains its completion receipt; elapsed time alone cannot make it pass. minimumPostFixAttempts (1..5) prevents a decisive negative result from stopping below the declared minimum. Deadlines, unavailable sources and conflicting observations can still end inconclusively. Read needed screenshot resources promptly: the existing four-file quota can expire an earlier phase image.
The MCP boundary is intentionally small. Framework-specific protocol details stay inside adapters, while session ownership, same-origin navigation, bounds, redaction, and recovery stay centralized.
How it differs from native macOS and iOS build/debug skills
web-debug-mcp complements Codex build/debug skills; it is not a replacement for them and it is not another Xcode automation layer.
| Surface | Primary target | Main job | Typical evidence |
|---|---|---|---|
build-macos-apps skills |
macOS apps, Swift, Xcode, AppKit, SwiftUI | Build, run, package, and debug native macOS software | Xcode/SwiftPM builds, app launch state, macOS logs, window behavior, signing and packaging evidence |
build-ios-apps skills |
iOS apps and Simulator | Build, launch, inspect, test, and profile native iOS software | Simulator UI, adb/Xcode-style logs, ETTrace, memgraphs, App Intents, SwiftUI behavior |
web-debug-mcp |
Local web apps in Chromium or Safari | Reproduce browser behavior and join browser evidence with bounded framework/runtime context | DOM, console, network metadata, CDP pauses, React commits, Angular DOM-host state, Vue component updates, Vite transforms, Next traces, screenshots, replay frames |
The difference is both the target and the integration model:
- Native build skills are Codex workflows for operating native development environments and their simulators or app runtimes.
web-debug-mcpis a repository-owned MCP server that any compatible MCP client can call over stdio.- Native skills help build and debug the app itself; this server observes a running web target and produces structured browser/runtime evidence.
- A project may use both: a native skill for a macOS or iOS shell, and
web-debug-mcpfor a web frontend, embedded web surface, or local browser flow.
What it provides
web-debug MCP questions
How do I install web-debug-mcp?
You can install it as a standalone MCP server using npx, or as a plugin for Codex and Claude Code which includes both workflow skills and the MCP connection.
Does this server require a hosted service?
No, the server runs locally over stdio and does not require any hosted service.
What can I debug with this tool?
It is designed for debugging DOM, console, network, and JavaScript issues, as well as inspecting React state, Vite HMR behavior, and Next.js routes.
How can I check if my configuration is correct?
You can use the 'web-debug-mcp doctor' command to check your project, browser configuration, CDP endpoints, and framework readiness.