BrowserTools MCP for Claude Code: Setup & Config

What you can do with BrowserTools in Claude Code

Browser evidence and Lighthouse audits in one MCP workflow, with an explicit inactive-project caveat.

• Investigate front-end failures using console and network evidence.
• Sequence auditing or debugging operations through dedicated modes.

Before you start: BrowserTools in Claude Code

• Chrome with the BrowserTools extension
• A compatible MCP client
• Node.js tooling
• A separate browser-tools-server process
• The BrowserToolsMCP DevTools panel open

Run npx @agentdeskai/browser-tools-server@latest separately. The MCP package belongs in the client configuration. The project is no longer active.

BrowserTools Claude Code configuration

1. Choose Claude Code configuration scope

   For BrowserTools MCP, open Project scope: .mcp.json at the repository root. Project JSON: merge into mcpServers; user scope: use the CLI.

2. Add BrowserTools MCP to Claude Code

   Use the browser-tools-mcp entry below in mcpServers. Keep BrowserTools MCP's documented stdio connection fields and your other Claude Code entries.

3. Check BrowserTools MCP in Claude Code

   BrowserTools MCP: Inspect claude mcp list and /mcp status.

{
  "mcpServers": {
    "browser-tools-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@agentdeskai/browser-tools-mcp@latest"
      ],
      "env": {}
    }
  }
}

claude mcp add-json --scope project 'browser-tools-mcp' '{"type":"stdio","command":"npx","args":["@agentdeskai/browser-tools-mcp@latest"],"env":{}}'

BrowserTools tools available to Claude Code

BrowserTools's stored tool list documents 7 tools; compare it with Claude Code's connected tool list, because the stored list is not a live check.

runAccessibilityAudit

For BrowserTools's runAccessibilityAudit, review the permission request and arguments in Claude Code before approval.

runPerformanceAudit

For BrowserTools's runPerformanceAudit, review the permission request and arguments in Claude Code before approval.

runSEOAudit

For BrowserTools's runSEOAudit, review the permission request and arguments in Claude Code before approval.

Review page-level search optimization factors.

runBestPracticesAudit

For BrowserTools's runBestPracticesAudit, review the permission request and arguments in Claude Code before approval.

Check the page against web development practices.

runAuditMode

For BrowserTools's runAuditMode, review the permission request and arguments in Claude Code before approval.

Run auditing tools in sequence, adding a NextJS check when detected.

runNextJSAudit

For BrowserTools's runNextJSAudit, review the permission request and arguments in Claude Code before approval.

runDebuggerMode

For BrowserTools's runDebuggerMode, review the permission request and arguments in Claude Code before approval.

Execute the debugging tools in their prescribed order.

BrowserTools: full stored tool descriptions

Troubleshooting BrowserTools in Claude Code

• If BrowserTools MCP fails to start, check npx @agentdeskai/browser-tools-mcp@latest (Node.js/npm), the working directory, and Claude Code's selected scope; inspect claude mcp list and /mcp.
• BrowserTools MCP uses stdio here: Claude Code must keep the configured process running; protocol output belongs on stdout and diagnostics on stderr.
• Known limitation: The project explicitly states that it is no longer active.
• Known limitation: Requires an extension and two distinct server components.
• General Claude Code troubleshooting lives in the /clients/claude-code guide.

Frequently asked questions