English | فارسی

visual-inspector-mcp

An MCP (Model Context Protocol) server that lets Claude Code — or any MCP-compatible client — visually inspect rendered web pages through a persistent headless Chromium browser powered by Playwright.

Instead of guessing UI state from source code alone, your AI assistant can navigate to a URL, take a screenshot, click elements, resize the viewport, and read browser console logs — all over a single persistent page session.

Table of Contents

• Why this exists
• Tools
  • navigate
  • screenshot
  • click
  • resize
  • console_logs
• Installation
  • Prerequisites
  • Clone and install dependencies
• Usage
  • Run directly
  • Register with Claude Code
  • Register with Claude Desktop
  • Example workflow
• Running the smoke test
• Security notes
• License

Why this exists

Most AI coding assistants only read your source files. visual-inspector-mcp gives your assistant a real browser window so it can:

• See what the page actually looks like (not just what the HTML says)
• Interact with the UI — open menus, navigate tabs, trigger modals — before screenshotting
• Debug visually by correlating a broken layout with console errors in the same session
• Check responsive breakpoints by resizing the viewport on the fly

All through a single, lightweight MCP server — no Docker, no additional services.

Tools

Tool	Description	Side-effects?
navigate	Load a URL in the persistent headless page	Opens network connections
screenshot	Capture the viewport, full page, or a CSS selector	Read-only
click	Click an element by CSS selector or Playwright locator	Modifies page state
resize	Resize the browser viewport	Modifies page state
console_logs	Return recent browser console messages and page errors	Read-only

Each tool is annotated with readOnlyHint, destructiveHint, and openWorldHint metadata so MCP clients can surface appropriate confirmation prompts.

navigate

Load a URL in the persistent browser page. The page stays open for later click, screenshot, or console_logs calls.

Param	Type	Required	Notes
url	string	yes	URL to load (supports http://, https://, file://, and data: URIs)
waitForSelector	string	no	Wait for this CSS/Playwright selector before returning — useful for SPAs

Returns the resolved URL and page title on one line: https://example.com — "Example Domain".

screenshot

Screenshot the current page and return it as a base64-encoded image block.

Param	Type	Required	Notes
selector	string	no	Capture only this element (cheapest); CSS selector or Playwright locator
fullPage	boolean	no	Capture the full scrollable page (most expensive); defaults to viewport
format	"png" | "jpeg"	no	png (default, lossless) or jpeg (smaller; fine for layout checks)
quality	number 1–100	no	JPEG quality (default 80); ignored for PNG

Requires navigate to have been called first.

click

Click an element to reach a UI state (open a menu, modal, or tab) before screenshotting it.

Param	Type	Required	Notes
selector	string	yes	CSS selector or Playwright locator of the element to click

resize

Resize the browser viewport to check a responsive breakpoint.

Param	Type	Required	Notes
width	number	yes	Viewport width in pixels
height	number	yes	Viewport height in pixels

console_logs

Return recent browser console messages and page errors — useful for correlating a visual glitch with a JavaScript error.

Param	Type	Required	Notes
limit	number	no	Max entries to return, most recent first (default 30)
level	"all" | "error"	no	"all" (default) or errors/warnings only
clear	boolean	no	Clear the log buffer after reading
withTimestamps	boolean	no	Prepend ISO timestamps to each entry (default false)

Installation

Prerequisites

• Node.js 18+ (for native fetch and ESM support)
• A terminal / shell

Clone and install dependencies

git clone https://github.com/MatinMHF/visual-inspector-mcp.git
cd visual-inspector-mcp
npm install          # also runs `playwright install chromium` via postinstall

If Chromium is not installed automatically, run:

npx playwright install chromium

Usage

Run directly

node index.js

The server communicates over stdio, so it is meant to be launched by an MCP client, not run interactively on its own.

Register with Claude Code

claude mcp add visual-inspector -s user -- node /path/to/visual-inspector-mcp/index.js

On Windows PowerShell, quote the -- separator to prevent PowerShell from silently stripping it:

claude mcp add visual-inspector -s user "--" node "C:/path/to/visual-inspector-mcp/index.js"

Register with Claude Desktop (or any MCP-compatible client)

Add an entry to your client's MCP server config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "visual-inspector": {
      "command": "node",
      "args": ["C:/path/to/visual-inspector-mcp/index.js"]
    }
  }
}

Example workflow

A typical session once the server is registered with your MCP client:

1. "Navigate to my dev server" → calls navigate with http://localhost:3000
2. "Take a screenshot" → calls screenshot to see the current rendered UI
3. "Click the hamburger menu" → calls click with the selector, then screenshot again
4. "Check it at mobile width" → calls resize with { width: 375, height: 667 }, then screenshot
5. "Any JS errors?" → calls console_logs with { level: "error" }

Running the smoke test

A self-contained end-to-end smoke test spins up the server as a subprocess, speaks MCP over stdio, and exercises all five tools:

npm test

The test writes test-full.png and test-element.png to the working directory as proof that screenshots are working. Both files can be deleted afterwards.

Security notes

• The server launches a headless Chromium instance; it has access to your local network and filesystem via file:// URLs.
• Only register it with MCP clients and sessions you trust.
• click is marked destructiveHint: true — well-behaved clients should confirm before invoking it on production pages.
• Because every tool has openWorldHint: true (real network calls), avoid pointing it at sensitive internal services without understanding the risk.

License

MIT — see LICENSE for details.