webmcp-chrome-devtools-quickstart
AI-driven browser automation using Chrome DevTools MCP with WebMCP tools for structured, token-efficient interactions
How do I install this agent skill?
npx skills add https://github.com/reason-machines/devtools-skills --skill webmcp-chrome-devtools-quickstartIs this agent skill safe to install?
- Gen Agent Trust Hubwarn
This skill provides browser automation capabilities by executing remote packages from NPM and providing tools to run arbitrary JavaScript in a browser. It also presents a surface for indirect prompt injection through its interaction with external web content.
- Socketpass
No alerts
- Snykwarn
Risk: MEDIUM · 2 issues
What does this agent skill do?
WebMCP Chrome DevTools Quickstart
Skill by ara.so — Devtools Skills collection.
This skill teaches AI agents how to use WebMCP with Chrome DevTools MCP to enable structured, token-efficient browser automation. Instead of screenshot-based workflows, WebMCP lets you register JavaScript functions as AI-callable tools, reducing token usage by up to 89%.
What This Project Does
WebMCP turns your website's JavaScript functions into AI-callable tools using the Model Context Protocol (MCP). The Chrome DevTools MCP server connects to Chrome via the Chrome DevTools Protocol (CDP) and provides:
- 26 browser automation tools (navigation, interaction, inspection, tab management)
- WebMCP tool discovery (
list_webmcp_tools) - WebMCP tool execution (
call_webmcp_tool)
Architecture:
AI Client → Chrome DevTools MCP → Chrome (CDP) → Your Website (navigator.modelContext)
Installation
1. Clone and Run Demo
git clone https://github.com/WebMCP-org/chrome-devtools-quickstart.git
cd chrome-devtools-quickstart
npm install
npm run dev
# Opens http://localhost:5173
2. Add MCP Server to AI Client
Claude Code:
claude mcp add chrome-devtools npx @mcp-b/chrome-devtools-mcp@latest
claude mcp add --transport http webmcp-docs https://docs.mcp-b.ai/mcp
Cursor (.cursor/mcp.json):
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["@mcp-b/chrome-devtools-mcp@latest"]
},
"webmcp-docs": {
"url": "https://docs.mcp-b.ai/mcp"
}
}
}
Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["@mcp-b/chrome-devtools-mcp@latest"]
},
"webmcp-docs": {
"url": "https://docs.mcp-b.ai/mcp"
}
}
}
Windsurf (mcp_config.json):
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["@mcp-b/chrome-devtools-mcp@latest"]
},
"webmcp-docs": {
"command": "npx",
"args": ["mcp-remote", "https://docs.mcp-b.ai/mcp"]
}
}
}
3. Install in Your Own Project
npm install @mcp-b/global
// Must be imported FIRST
import '@mcp-b/global';
// Now navigator.modelContext is available
Registering WebMCP Tools
Basic Tool (No Parameters)
import '@mcp-b/global';
navigator.modelContext.registerTool({
name: "get_page_title",
description: "Returns the current page title",
inputSchema: {
type: "object",
properties: {}
},
async execute() {
return {
content: [
{ type: "text", text: document.title }
]
};
}
});
Tool with Parameters
import '@mcp-b/global';
let counter = 0;
navigator.modelContext.registerTool({
name: "set_counter",
description: "Sets the counter to the desired value",
inputSchema: {
type: "object",
properties: {
newCounterValue: {
type: "number",
description: "The number to set the counter to"
}
},
required: ["newCounterValue"]
},
async execute(args) {
counter = args.newCounterValue;
// Update UI
document.getElementById('counter').textContent = counter;
return {
content: [
{ type: "text", text: `Counter is now ${counter}` }
]
};
}
});
Tool with Complex Input Schema
import '@mcp-b/global';
navigator.modelContext.registerTool({
name: "create_calendar_event",
description: "Creates a new calendar event",
inputSchema: {
type: "object",
properties: {
title: {
type: "string",
description: "Event title"
},
date: {
type: "string",
description: "Event date in YYYY-MM-DD format"
},
startTime: {
type: "string",
description: "Start time in HH:MM format"
},
endTime: {
type: "string",
description: "End time in HH:MM format"
},
description: {
type: "string",
description: "Event description (optional)"
}
},
required: ["title", "date", "startTime", "endTime"]
},
async execute(args) {
const event = {
id: crypto.randomUUID(),
...args
};
// Save to state
window.calendarEvents = window.calendarEvents || [];
window.calendarEvents.push(event);
// Update UI
renderCalendar();
return {
content: [
{
type: "text",
text: `Created event "${event.title}" on ${event.date} from ${event.startTime} to ${event.endTime}`
}
]
};
}
});
Tool with Error Handling
import '@mcp-b/global';
navigator.modelContext.registerTool({
name: "toggle_theme",
description: "Toggles between light and dark theme",
inputSchema: {
type: "object",
properties: {}
},
async execute() {
try {
const body = document.body;
const currentTheme = body.getAttribute('data-theme') || 'light';
const newTheme = currentTheme === 'light' ? 'dark' : 'light';
body.setAttribute('data-theme', newTheme);
return {
content: [
{ type: "text", text: `Theme switched to ${newTheme} mode` }
]
};
} catch (error) {
return {
content: [
{ type: "text", text: `Error toggling theme: ${error.message}` }
],
isError: true
};
}
}
});
Key Chrome DevTools MCP Tools
Navigation
// Navigate to a page
await use_mcp_tool("chrome-devtools", "navigate_page", {
url: "http://localhost:5173"
});
// Go back
await use_mcp_tool("chrome-devtools", "go_back", {});
// Refresh
await use_mcp_tool("chrome-devtools", "refresh", {});
WebMCP Tool Discovery
// List all WebMCP tools on current page
const result = await use_mcp_tool("chrome-devtools", "list_webmcp_tools", {});
// Result:
// {
// content: [
// {
// type: "text",
// text: JSON.stringify([
// {
// name: "get_counter",
// description: "Returns the current counter value",
// inputSchema: { type: "object", properties: {} }
// },
// {
// name: "set_counter",
// description: "Sets the counter to the desired value",
// inputSchema: {
// type: "object",
// properties: {
// newCounterValue: { type: "number", description: "..." }
// }
// }
// }
// ])
// }
// ]
// }
WebMCP Tool Execution
// Call a WebMCP tool
const result = await use_mcp_tool("chrome-devtools", "call_webmcp_tool", {
name: "set_counter",
arguments: {
newCounterValue: 42
}
});
// Result:
// {
// content: [
// { type: "text", text: "Counter is now 42" }
// ]
// }
Screenshots and Inspection
// Take screenshot
const screenshot = await use_mcp_tool("chrome-devtools", "take_screenshot", {});
// Evaluate JavaScript
const result = await use_mcp_tool("chrome-devtools", "evaluate_script", {
script: "document.querySelectorAll('.event-card').length"
});
Interaction
// Click element
await use_mcp_tool("chrome-devtools", "click", {
selector: "#submit-button"
});
// Fill input
await use_mcp_tool("chrome-devtools", "fill", {
selector: "#email-input",
value: "user@example.com"
});
// Hover
await use_mcp_tool("chrome-devtools", "hover", {
selector: ".tooltip-trigger"
});
Common Patterns
Complete AI Workflow
// 1. Navigate to page
await use_mcp_tool("chrome-devtools", "navigate_page", {
url: "http://localhost:5173"
});
// 2. Discover available tools
const tools = await use_mcp_tool("chrome-devtools", "list_webmcp_tools", {});
console.log("Available tools:", tools);
// 3. Call a tool
const result = await use_mcp_tool("chrome-devtools", "call_webmcp_tool", {
name: "set_counter",
arguments: { newCounterValue: 42 }
});
// 4. Verify with another tool call
const verification = await use_mcp_tool("chrome-devtools", "call_webmcp_tool", {
name: "get_counter",
arguments: {}
});
Multi-Step Form Interaction
import '@mcp-b/global';
// Register form submission tool
navigator.modelContext.registerTool({
name: "submit_contact_form",
description: "Submits the contact form with user details",
inputSchema: {
type: "object",
properties: {
name: { type: "string", description: "User's full name" },
email: { type: "string", description: "User's email address" },
message: { type: "string", description: "Contact message" }
},
required: ["name", "email", "message"]
},
async execute(args) {
document.getElementById('name').value = args.name;
document.getElementById('email').value = args.email;
document.getElementById('message').value = args.message;
// Trigger validation
const form = document.getElementById('contact-form');
const isValid = form.checkValidity();
if (!isValid) {
return {
content: [{ type: "text", text: "Form validation failed" }],
isError: true
};
}
form.submit();
return {
content: [{ type: "text", text: "Contact form submitted successfully" }]
};
}
});
State Management Tool
import '@mcp-b/global';
// Register state getter
navigator.modelContext.registerTool({
name: "get_app_state",
description: "Returns the current application state",
inputSchema: {
type: "object",
properties: {}
},
async execute() {
const state = {
user: window.currentUser || null,
theme: document.body.getAttribute('data-theme'),
activeView: window.location.hash.slice(1),
notifications: window.notifications?.length || 0
};
return {
content: [
{ type: "text", text: JSON.stringify(state, null, 2) }
]
};
}
});
// Register state setter
navigator.modelContext.registerTool({
name: "update_app_state",
description: "Updates application state",
inputSchema: {
type: "object",
properties: {
theme: { type: "string", enum: ["light", "dark"] },
activeView: { type: "string" }
}
},
async execute(args) {
if (args.theme) {
document.body.setAttribute('data-theme', args.theme);
}
if (args.activeView) {
window.location.hash = args.activeView;
}
return {
content: [{ type: "text", text: "State updated successfully" }]
};
}
});
Tool with DOM Manipulation
import '@mcp-b/global';
navigator.modelContext.registerTool({
name: "add_todo_item",
description: "Adds a new todo item to the list",
inputSchema: {
type: "object",
properties: {
text: {
type: "string",
description: "The todo item text"
},
priority: {
type: "string",
enum: ["low", "medium", "high"],
description: "Priority level"
}
},
required: ["text"]
},
async execute(args) {
const todoList = document.getElementById('todo-list');
const todoItem = document.createElement('li');
todoItem.className = `todo-item priority-${args.priority || 'medium'}`;
todoItem.innerHTML = `
<span class="todo-text">${args.text}</span>
<button class="delete-btn">Delete</button>
`;
todoList.appendChild(todoItem);
// Add event listener
todoItem.querySelector('.delete-btn').addEventListener('click', () => {
todoItem.remove();
});
return {
content: [
{
type: "text",
text: `Added todo: "${args.text}" with ${args.priority || 'medium'} priority`
}
]
};
}
});
Running Benchmarks
Compare token usage between screenshot-based and WebMCP-based workflows:
# Add your API key
echo "ANTHROPIC_API_KEY=sk-ant-..." > .env
# Simple benchmark (counter app)
npm run benchmark:simple:direct
# Complex benchmark (calendar app)
npm run benchmark:complex:direct
Expected Results:
- Simple task: 89% token reduction
- Complex task: 77% token reduction
Configuration
Custom Chrome Launch Options
Create chrome-devtools.config.js:
export default {
chromeOptions: {
headless: false,
userDataDir: './chrome-profile',
args: [
'--window-size=1920,1080',
'--disable-blink-features=AutomationControlled'
]
},
port: 9222
};
Tool Registration Best Practices
import '@mcp-b/global';
// Wait for DOM ready
if (document.readyState === 'loading') {
document.addEventListener('DOMContentLoaded', registerTools);
} else {
registerTools();
}
function registerTools() {
// Register all tools here
navigator.modelContext.registerTool({
name: "my_tool",
description: "Clear, specific description of what this tool does",
inputSchema: {
type: "object",
properties: {
// Use descriptive property names
// Add helpful descriptions
// Include type constraints
},
required: [] // Be explicit about required fields
},
async execute(args) {
try {
// Validate inputs
// Perform action
// Return structured response
return {
content: [{ type: "text", text: "Success message" }]
};
} catch (error) {
return {
content: [{ type: "text", text: error.message }],
isError: true
};
}
}
});
}
Troubleshooting
navigator.modelContext is undefined
Cause: @mcp-b/global not imported or imported after tool registration.
Solution:
// CORRECT: Import first
import '@mcp-b/global';
import './my-tools.js';
// WRONG: Tool imports before @mcp-b/global
import './my-tools.js';
import '@mcp-b/global';
No tools found by list_webmcp_tools
Cause: Tools not registered yet or page not fully loaded.
Solution:
// Wait for page load
window.addEventListener('load', () => {
navigator.modelContext.registerTool({
// ...
});
});
// Or check in AI workflow
await use_mcp_tool("chrome-devtools", "evaluate_script", {
script: "typeof navigator.modelContext !== 'undefined' && navigator.modelContext.tools.size"
});
Tool execution fails with isError: true
Debug by inspecting console:
// In AI workflow
const consoleOutput = await use_mcp_tool("chrome-devtools", "evaluate_script", {
script: `
const errors = [];
console.error = (...args) => errors.push(args.join(' '));
// ... trigger tool call ...
JSON.stringify(errors);
`
});
Chrome connection fails
Cause: Chrome not running or firewall blocking port 9222.
Solution:
# Launch Chrome manually with remote debugging
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
--remote-debugging-port=9222 \
--user-data-dir=/tmp/chrome-debug
# Or check if port is in use
lsof -i :9222
Hot reload breaks tool registration
Cause: Vite HMR doesn't re-run @mcp-b/global initialization.
Solution:
// Force full reload for tool changes
if (import.meta.hot) {
import.meta.hot.accept(() => {
window.location.reload();
});
}
Advanced Usage
Multiple Tools in One File
import '@mcp-b/global';
const tools = [
{
name: "get_user_info",
description: "Get current user information",
inputSchema: { type: "object", properties: {} },
async execute() {
return {
content: [{ type: "text", text: JSON.stringify(window.currentUser) }]
};
}
},
{
name: "logout",
description: "Log out the current user",
inputSchema: { type: "object", properties: {} },
async execute() {
window.currentUser = null;
localStorage.removeItem('authToken');
return {
content: [{ type: "text", text: "Logged out successfully" }]
};
}
}
];
tools.forEach(tool => navigator.modelContext.registerTool(tool));
Async Tool with External API
import '@mcp-b/global';
navigator.modelContext.registerTool({
name: "fetch_weather",
description: "Fetches weather data for a city",
inputSchema: {
type: "object",
properties: {
city: { type: "string", description: "City name" }
},
required: ["city"]
},
async execute(args) {
try {
const apiKey = import.meta.env.VITE_WEATHER_API_KEY;
const response = await fetch(
`https://api.openweathermap.org/data/2.5/weather?q=${args.city}&appid=${apiKey}`
);
if (!response.ok) {
throw new Error(`Weather API returned ${response.status}`);
}
const data = await response.json();
return {
content: [
{
type: "text",
text: `Weather in ${args.city}: ${data.weather[0].description}, ${Math.round(data.main.temp - 273.15)}°C`
}
]
};
} catch (error) {
return {
content: [{ type: "text", text: `Failed to fetch weather: ${error.message}` }],
isError: true
};
}
}
});
Resources
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/reason-machines/devtools-skills/webmcp-chrome-devtools-quickstart">View webmcp-chrome-devtools-quickstart on skillZs</a>