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

Related MCP server: Browser MCP

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

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.

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.

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.

resize

Resize the browser viewport to check a responsive breakpoint.

console_logs

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

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.