Skip to content
Back to search

chrome-devtools-mcp

An MCP Server for Chrome DevTools, following the Chrome DevTools Protocol. Integrates with Claude Desktop and Claude Code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/benjaminr--chrome-devtools-mcp/badge.svg)](/listings/benjaminr--chrome-devtools-mcp)

HTML

<a href="/listings/benjaminr--chrome-devtools-mcp"><img src="/api/listings/benjaminr--chrome-devtools-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Option 1: Claude Desktop Extension (Easiest)

**Download the pre-built extension:** 1. Download the latest `.dxt` file from [Releases](https://github.com/benjaminr/chrome-devtools-mcp/releases) 2. Open Claude Desktop 3. Go to Extensions and install the downloaded `.dxt` file 4. Configure Chrome path if needed in extension settings

The extension includes all dependencies and is ready to use immediately!

Option 2: MCP CLI (Advanced)

**Quick Install (most common):**

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

> **Note**: The `mcp` command is part of the [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk). Install it with `pip install mcp` if not already available.

**All Installation Options:**

# Clone the repository
git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

# The --with-editable flag uses pyproject.toml to install dependencies

# Basic installation with local dependencies
mcp install server.py --with-editable .

# Install with custom name
mcp install server.py -n "Chrome DevTools MCP" --with-editable .

# Install with environment variables
mcp install server.py -n "Chrome DevTools MCP" --with-editable . -v CHROME_DEBUG_PORT=9222

# Install with additional packages if needed
mcp install server.py -n "Chrome DevTools MCP" --with-editable . --with websockets --with aiohttp

# Install with environment file (copy .env.example to .env first)
cp .env.example .env
# Edit .env with your settings
mcp install server.py -n "Chrome DevTools MCP" --with-editable . -f .env

Option 3: Claude Code Integration

**For Claude Code CLI users:**

1. **Clone this repository**

git clone https://github.com/benjaminr/chrome-devtools-mcp.git
cd chrome-devtools-mcp

2. **Install dependencies with UV (creates venv)**

uv sync  # Creates .venv and installs dependencies

3. **Add MCP server using Claude CLI with absolute paths**

**IMPORTANT**: Claude Code needs absolute paths to both the Python interpreter and the server script to work correctly.

**Recommended setup using absolute paths:**

# Get the absolute paths
SERVER_PATH="$(pwd)/server.py"
PYTHON_PATH="$(pwd)/.venv/bin/python"

# Add the server with absolute paths
claude mcp add chrome-devtools "$PYTHON_PATH" "$SERVER_PATH" -e CHROME_DEBUG_PORT=9222

**Alternative: Using the system Python (if dependencies are installed globally):**

# Only if you've installed dependencies globally
claude mcp add chrome-devtools python "$(pwd)/server.py" -e CHROME_DEBUG_PORT=9222

**With custom scope:**

# Add to user scope (available across all projects)
claude mcp add chrome-devtools "$(pwd)/.venv/bin/python" "$(pwd)/server.py" -s user -e CHROME_DEBUG_PORT=9222

# Add to project scope (only for this project)
claude mcp add chrome-devtools "$(pwd)/.venv/bin/python" "$(pwd)/server.py" -s project -e CHROME_DEBUG_PORT=9222

4. **Verify installation**

# List configured MCP servers
claude mcp list

# Get details about the server (check that paths are absolute)
claude mcp get chrome-devtools

# The output should show absolute paths like:
# Command: /Users/you/chrome-devtools-mcp/.venv/bin/python
# Args: ["/Users/you/chrome-devtools-mcp/server.py"]

**Common Path Issues and Solutions:** - **Problem**: "python: command not found" or "server.py not found" - **Solution**: Use absolute paths as shown above - **Problem**: "ModuleNotFoundError" when server starts - **Solution**: Use the venv Python interpreter that has dependencies installed - **Problem**: Server doesn't start or shows as disconnected - **Solution**: Test the command manually: `/path/to/.venv/bin/python /path/to/server.py`

Option 4: Manual Claude Desktop Setup

1. **Clone this repository**

git clone https://github.com/benjaminr/chrome-devtools-mcp.git

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 743 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Chrome DevTools MCP
  2. A Model Context Protocol (MCP) server that provides Chrome DevTools Protocol integration through MCP. This allows you to debug web applications by connecting to Chrome's developer tools.
  3. **Available as a Claude Desktop Extension (.dxt)** for easy one-click installation!
  4. ## What This Does
  5. This MCP server acts as a bridge between Claude and Chrome's debugging capabilities. Once installed in Claude Desktop, you can:
  6. - Connect Claude to any web application running in Chrome
  7. - Debug network requests, console errors, and performance issues
  8. - Inspect JavaScript objects and execute code in the browser context
  9. - Monitor your application in real-time through natural conversation with Claude
  10. **Note**: This is an MCP server that runs within Claude Desktop - you don't need to run any separate servers or processes.
  11. ## Features
  12. - **Network Monitoring**: Capture and analyse HTTP requests/responses with filtering options
  13. - **Console Integration**: Read browser console logs, analyse errors, and execute JavaScript
  14. - **Performance Metrics**: Timing data, resource loading, and memory utilisation
  15. - **Page Inspection**: DOM information, page metrics, and multi-frame support
  16. - **Storage Access**: Read cookies, localStorage, and sessionStorage
  17. - **Real-time Monitoring**: Live console output tracking
  18. - **Object Inspection**: Inspect JavaScript objects and variables
  19. ## Installation
  20. ### Option 1: Claude Desktop Extension (Easiest)
  21. **Download the pre-built extension:**
  22. 1. Download the latest `.dxt` file from [Releases](https://github.com/benjaminr/chrome-devtools-mcp/releases)
  23. 2. Open Claude Desktop
  24. 3. Go to Extensions and install the downloaded `.dxt` file
  25. 4. Configure Chrome path if needed in extension settings
  26. The extension includes all dependencies and is ready to use immediately!
  27. ### Option 2: MCP CLI (Advanced)
  28. **Quick Install (most common):**
  29. ```bash
  30. git clone https://github.com/benjaminr/chrome-devtools-mcp.git
  31. cd chrome-devtools-mcp
  32. mcp install server.py -n "Chrome DevTools MCP" --with-editable .
  33. ```
  34. > **Note**: The `mcp` command is part of the [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk). Install it with `pip install mcp` if not already available.
  35. **All Installation Options:**
  36. ```bash
  37. # Clone the repository
  38. git clone https://github.com/benjaminr/chrome-devtools-mcp.git
  39. cd chrome-devtools-mcp
  40. # The --with-editable flag uses pyproject.toml to install dependencies
  41. # Basic installation with local dependencies
  42. mcp install server.py --with-editable .
  43. # Install with custom name
  44. mcp install server.py -n "Chrome DevTools MCP" --with-editable .
  45. # Install with environment variables
  46. mcp install server.py -n "Chrome DevTools MCP" --with-editable . -v CHROME_DEBUG_PORT=9222
  47. # Install with additional packages if needed
  48. mcp install server.py -n "Chrome DevTools MCP" --with-editable . --with websockets --with aiohttp
  49. # Install with environment file (copy .env.example to .env first)
  50. cp .env.example .env
  51. # Edit .env with your settings
  52. mcp install server.py -n "Chrome DevTools MCP" --with-editable . -f .env
  53. ```
  54. ### Option 3: Claude Code Integration
  55. **For Claude Code CLI users:**
  56. 1. **Clone this repository**
  57. ```bash
  58. git clone https://github.com/benjaminr/chrome-devtools-mcp.git
  59. cd chrome-devtools-mcp
  60. ```
  61. 2. **Install dependencies with UV (creates venv)**
  62. ```bash
  63. uv sync # Creates .venv and installs dependencies
  64. ```
  65. 3. **Add MCP server using Claude CLI with absolute paths**
  66. **IMPORTANT**: Claude Code needs absolute paths to both the Python interpreter and the server script to work correctly.
  67. **Recommended setup using absolute paths:**
  68. ```bash
  69. # Get the absolute paths
  70. SERVER_PATH="$(pwd)/server.py"
  71. PYTHON_PATH="$(pwd)/.venv/bin/python"
  72. # Add the server with absolute paths
  73. claude mcp add chrome-devtools "$PYTHON_PATH" "$SERVER_PATH" -e CHROME_DEBUG_PORT=9222
  74. ```
  75. **Alternative: Using the system Python (if dependencies are installed globally):**
  76. ```bash
  77. # Only if you've installed dependencies globally
  78. claude mcp add chrome-devtools python "$(pwd)/server.py" -e CHROME_DEBUG_PORT=9222
  79. ```
  80. **With custom scope:**
  81. ```bash
  82. # Add to user scope (available across all projects)
  83. claude mcp add chrome-devtools "$(pwd)/.venv/bin/python" "$(pwd)/server.py" -s user -e CHROME_DEBUG_PORT=9222
  84. # Add to project scope (only for this project)
  85. claude mcp add chrome-devtools "$(pwd)/.venv/bin/python" "$(pwd)/server.py" -s project -e CHROME_DEBUG_PORT=9222
  86. ```
  87. 4. **Verify installation**
  88. ```bash
  89. # List configured MCP servers
  90. claude mcp list
  91. # Get details about the server (check that paths are absolute)
  92. claude mcp get chrome-devtools
  93. # The output should show absolute paths like:
  94. # Command: /Users/you/chrome-devtools-mcp/.venv/bin/python
  95. # Args: ["/Users/you/chrome-devtools-mcp/server.py"]
  96. ```
  97. **Common Path Issues and Solutions:**
  98. - **Problem**: "python: command not found" or "server.py not found"
  99. - **Solution**: Use absolute paths as shown above
  100. - **Problem**: "ModuleNotFoundError" when server starts
  101. - **Solution**: Use the venv Python interpreter that has dependencies installed
  102. - **Problem**: Server doesn't start or shows as disconnected
  103. - **Solution**: Test the command manually: `/path/to/.venv/bin/python /path/to/server.py`
  104. ### Option 4: Manual Claude Desktop Setup
  105. 1. **Clone this repository**
  106. ```bash
  107. git clone https://github.com/benjaminr/chrome-devtools-mcp.git
  108. cd chrome-devtools-mcp
  109. ```
  110. 2. **Install dependencies**
  111. **With uv (recommended):**
  112. ```bash
  113. uv sync
  114. ```
  115. **With pip:**
  116. ```bash
  117. pip install -r requirements.txt
  118. ```
  119. 3. **Add to Claude Desktop configuration**
  120. Edit your Claude Desktop config file:
  121. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  122. - **Windows**: `%APPDATA%/Claude/claude_desktop_config.json`
  123. ```json
  124. {
  125. "mcpServers": {
  126. "chrome-devtools": {
  127. "command": "python",
  128. "args": ["/absolute/path/to/chrome-devtools-mcp/server.py"],
  129. "env": {
  130. "CHROME_DEBUG_PORT": "9222"
  131. }
  132. }
  133. }
  134. }
  135. ```
  136. 4. **Restart Claude Desktop**
  137. ### Verify Installation
  138. After installation (either method), verify the server is available:
  139. 1. Open Claude Desktop
  140. 2. Look for MCP tools in the conversation
  141. 3. Try a simple command: `get_connection_status()`
  142. ### Alternative MCP Clients
  143. For other MCP clients, run the server directly:
  144. ```bash
  145. python server.py
  146. ```
  147. ## Quick Start
  148. Once installed in Claude Desktop, you can start debugging any web application:
  149. ### Debug Your Web Application
  150. **One-step setup (recommended):**
  151. ```
  152. start_chrome_and_connect("localhost:3000")
  153. ```
  154. *Replace `localhost:3000` with your application's URL*
  155. **If Chrome isn't found automatically:**
  156. ```
  157. start_chrome_and_connect("localhost:3000", chrome_path="/path/to/chrome")
  158. ```
  159. *Use the `chrome_path` parameter to specify a custom Chrome location*
  160. This command will:
  161. - Start Chrome with debugging enabled
  162. - Navigate to your application
  163. - Connect the MCP server to Chrome
  164. **Manual setup (if you prefer step-by-step):**
  165. ```
  166. start_chrome()
  167. navigate_to_url("localhost:3000")
  168. connect_to_browser()
  169. ```
  170. ### Start Debugging
  171. Once connected, use these commands:
  172. - `get_network_requests()` - View HTTP traffic
  173. - `get_console_error_summary()` - Analyse JavaScript errors
  174. - `inspect_console_object("window")` - Inspect any JavaScript object
  175. ## Available MCP Tools
  176. ### Chrome Management
  177. - `start_chrome(port?, url?, headless?, chrome_path?, auto_connect?)` - Start Chrome with remote debugging and optional auto-connection
  178. - `start_chrome_and_connect(url, port?, headless?, chrome_path?)` - Start Chrome, connect, and navigate in one step
  179. - `connect_to_browser(port?)` - Connect to existing Chrome instance
  180. - `navigate_to_url(url)` - Navigate to a specific URL
  181. - `disconnect_from_browser()` - Disconnect from browser
  182. - `get_connection_status()` - Check connection status
  183. ### Network Monitoring
  184. - `get_network_requests(filter_domain?, filter_status?, limit?)` - Get network requests with filtering
  185. - `get_network_response(request_id)` - Get detailed response data including body
  186. ### Console Tools
  187. - `get_console_logs(level?, limit?)` - Get browser console logs
  188. - `get_console_error_summary()` - Get organized summary of errors and warnings
  189. - `execute_javascript(code)` - Execute JavaScript in browser context
  190. - `clear_console()` - Clear the browser console
  191. - `inspect_console_object(expression)` - Deep inspect any JavaScript object
  192. - `monitor_console_live(duration_seconds)` - Monitor console output in real-time
  193. ### Page Analysis
  194. - `get_page_info()` - Get comprehensive page metrics and performance data
  195. - `evaluate_in_all_frames(code)` - Execute JavaScript in all frames/iframes
  196. - `get_performance_metrics()` - Get detailed performance metrics and resource timing
  197. ### Storage & Data
  198. - `get_storage_usage_and_quota(origin)` - Get storage usage and quota information
  199. - `clear_storage_for_origin(origin, storage_types?)` - Clear storage by type and origin
  200. - `get_all_cookies()` - Get all browser cookies
  201. - `clear_all_cookies()` - Clear all browser cookies
  202. - `set_cookie(name, value, domain, path?, expires?, http_only?, secure?, same_site?)` - Set a cookie
  203. - `get_cookies(domain?)` - Get browser cookies with optional domain filtering
  204. - `get_storage_key_for_frame(frame_id)` - Get storage key for a specific frame
  205. - `track_cache_storage(origin, enable?)` - Enable/disable cache storage tracking
  206. - `track_indexeddb(origin, enable?)` - Enable/disable IndexedDB tracking
  207. - `override_storage_quota(origin, quota_size_mb?)` - Override storage quota
  208. ## Use Cases
  209. ### Debugging API Calls in Your Web Application
  210. When your web application makes API calls that fail or return unexpected data:
  211. **Easy setup:** Use the one-step command to start Chrome and navigate to your app:
  212. **Example workflow:**
  213. ```
  214. You: "I need to debug my React app at localhost:3000"
  215. Claude: I'll start Chrome with debugging enabled and navigate to your app.
  216. start_chrome_and_connect("localhost:3000")
  217. Perfect! Chrome is now running with debugging enabled and connected to your app. Let me check for any failed network requests:
  218. get_network_requests(filter_status=500)
  219. I can see there are 3 failed requests to your API. Let me get the details of the first one:
  220. get_network_response("request-123")
  221. ```
  222. **Manual setup (if you prefer):**
  223. 1. **Start Chrome**: Use `start_chrome()`
  224. 2. **Navigate to your app**: Use `navigate_to_url("localhost:3000")`
  225. 3. **Connect**: Use `connect_to_browser()`
  226. 4. **Monitor network traffic**: Use `get_network_requests()` to see all API calls
  227. ### Checking JavaScript Console Errors
  228. When your web application has JavaScript errors or unexpected behaviour:
  229. 1. **Navigate to your application** in the connected Chrome instance
  230. 2. **Check for console errors**: Use `get_console_error_summary()` to see all errors
  231. 3. **Monitor live errors**: Use `monitor_console_live(10)` to watch for new errors as you interact
  232. 4. **Inspect variables**: Use `inspect_console_object("myVariable")` to examine application state
  233. **Example workflow:**
  234. ```
  235. You: "My React component isn't updating properly"
  236. Claude: Let me check the JavaScript console for any errors.
  237. get_console_error_summary()
  238. I can see there are 2 JavaScript errors. Let me also monitor the console while you interact with the component:
  239. monitor_console_live(15)
  240. Now try clicking the component that isn't working. I'll watch for any new errors or warnings.
  241. ```
  242. ### Performance Debugging
  243. When your web application loads slowly or uses too much memory:
  244. 1. **Load your application** in the connected browser
  245. 2. **Check page metrics**: Use `get_page_info()` to see load times and resource counts
  246. 3. **Analyse performance**: Use `get_performance_metrics()` to see detailed timing data
  247. 4. **Monitor memory usage**: Check the memory information in the performance metrics
  248. **Example workflow:**
  249. ```
  250. You: "My application takes too long to load"
  251. Claude: Let me analyse the performance of your application.
  252. get_page_info()
  253. I can see your page has 47 scripts and took 3.2 seconds to load. Let me get more detailed performance data:
  254. get_performance_metrics()
  255. The main bottleneck is the initial JavaScript bundle which is 2.1MB. The DOM processing also takes 800ms.
  256. ```
  257. ### Debugging Authentication Issues
  258. When login or session management isn't working:
  259. 1. **Navigate to your login page**
  260. 2. **Check cookies**: Use `get_cookies()` to see authentication cookies
  261. 3. **Monitor network during login**: Use `monitor_console_live()` and `get_network_requests()` during the login process
  262. 4. **Examine stored data**: Use JavaScript execution to check localStorage/sessionStorage
  263. **Example workflow:**
  264. ```
  265. You: "Users can't stay logged in"
  266. Claude: Let me check the authentication setup.
  267. get_cookies()
  268. I can see the auth cookie is present. Let me check what happens during login by monitoring the network:
  269. get_network_requests(filter_domain="your-api.com")
  270. I notice the login request returns a 200 but no Set-Cookie header. Let me also check localStorage:
  271. execute_javascript("Object.keys(localStorage)")
  272. ```
  273. ### DOM Element Inspection
  274. - `get_document(depth?, pierce?)` - Retrieve DOM document structure
  275. - `query_selector(node_id, selector)` - Find single element by CSS selector
  276. - `query_selector_all(node_id, selector)` - Find multiple elements by CSS selector
  277. - `get_element_attributes(node_id)` - Get all attributes of an element
  278. - `get_element_outer_html(node_id)` - Get outer HTML of an element
  279. - `get_element_box_model(node_id)` - Get layout information
  280. - `describe_element(node_id, depth?)` - Get detailed element description
  281. - `get_element_at_position(x, y)` - Get element at screen position
  282. - `search_elements(query)` - Search DOM elements by text/attributes
  283. - `focus_element(node_id)` - Focus a DOM element
  284. ### CSS Style Analysis
  285. - `get_computed_styles(node_id)` - Get computed CSS styles
  286. - `get_inline_styles(node_id)` - Get inline styles
  287. - `get_matched_styles(node_id)` - Get all CSS rules matching an element
  288. - `get_stylesheet_text(stylesheet_id)` - Get stylesheet content
  289. - `get_background_colors(node_id)` - Get background colors and fonts
  290. - `get_platform_fonts(node_id)` - Get platform font information
  291. - `get_media_queries()` - Get all media queries
  292. - `collect_css_class_names(stylesheet_id)` - Collect CSS class names
  293. - `start_css_coverage_tracking()` - Start CSS coverage tracking
  294. - `stop_css_coverage_tracking()` - Stop and get CSS coverage results
  295. ## Common Commands
  296. | Task | Command |
  297. |------|---------|
  298. | Start Chrome and connect to app | `start_chrome_and_connect("localhost:3000")` |
  299. | Start Chrome (manual setup) | `start_chrome()` |
  300. | Navigate to page | `navigate_to_url("localhost:3000")` |
  301. | Connect to browser | `connect_to_browser()` |
  302. | See all network requests | `get_network_requests()` |
  303. | Find failed API calls | `get_network_requests(filter_status=404)` |
  304. | Check for JavaScript errors | `get_console_error_summary()` |
  305. | Watch console in real-time | `monitor_console_live(10)` |
  306. | Check page load performance | `get_page_info()` |
  307. | Examine a variable | `inspect_console_object("window.myApp")` |
  308. | View cookies | `get_cookies()` |
  309. | Run JavaScript | `execute_javascript("document.title")` |
  310. ## Configuration
  311. ### Environment Variables
  312. - `CHROME_DEBUG_PORT` - Chrome remote debugging port (default: 9222)
  313. ### MCP Compatibility
  314. - **MCP Protocol Version**: 2024-11-05
  315. - **Minimum Python Version**: 3.10+
  316. - **Supported MCP Clients**: Claude Desktop, any MCP-compatible client
  317. - **Package Manager**: uv (recommended) or pip
  318. ## Usage Workflow
  319. ### Prerequisites (Your Development Environment)
  320. - Have your web application running (e.g., `npm run dev`, `python -m http.server`, etc.)
  321. - Note the URL where your application is accessible
  322. ### Debugging Session
  323. 1. **Connect to your application** via Claude Desktop:
  324. ```
  325. start_chrome_and_connect("localhost:3000")
  326. ```
  327. *Replace with your application's URL*
  328. 2. **Debug your application** using the MCP tools:
  329. - Monitor network requests
  330. - Check console errors
  331. - Inspect JavaScript objects
  332. - Analyse performance
  333. 3. **Make changes to your code** in your editor
  334. 4. **Refresh or interact** with your application
  335. 5. **Continue debugging** with real-time data
  336. ### Manual Connection (Alternative)
  337. If you prefer step-by-step control:
  338. 1. `start_chrome()` - Launch Chrome with debugging
  339. 2. `navigate_to_url("your-app-url")` - Navigate to your application
  340. 3. `connect_to_browser()` - Connect the MCP server
  341. 4. Use debugging tools as needed
  342. ## Security Notes
  343. - Only use with development environments
  344. - Never connect to production Chrome instances
  345. - The server is designed for localhost debugging only
  346. - No data is stored permanently - all data is session-based
  347. ## Troubleshooting
  348. ### Server Shows as "Disabled" in Claude Desktop
  349. If the server appears in Claude but shows as "disabled", try these steps:
  350. 1. **Check Claude Desktop logs**:
  351. - **macOS**: `~/Library/Logs/Claude/mcp*.log`
  352. - **Windows**: `%APPDATA%/Claude/logs/mcp*.log`
  353. 2. **Common fixes**:
  354. ```bash
  355. # Reinstall with verbose output
  356. mcp remove "Chrome DevTools MCP"
  357. mcp install server.py -n "Chrome DevTools MCP" --with-editable . -v CHROME_DEBUG_PORT=9222
  358. # Check installation status
  359. mcp list
  360. # Test the server manually
  361. python3 server.py
  362. ```
  363. 3. **Check dependencies**:
  364. ```bash
  365. # Ensure all dependencies are available
  366. pip install mcp websockets aiohttp
  367. # Test imports
  368. python3 -c "from server import mcp; print('OK')"
  369. ```
  370. 4. **Restart Claude Desktop** completely (quit and reopen)
  371. ### Installation Issues
  372. - **MCP CLI not found**: Install MCP CLI from the [Python MCP SDK](https://github.com/modelcontextprotocol/python-sdk) with `pip install mcp`
  373. - **Server not appearing in Claude**:
  374. - For MCP CLI: Run `mcp list` to verify the server is installed
  375. - For manual setup: Check Claude Desktop configuration file path and JSON syntax
  376. - **Import errors**:
  377. - For MCP CLI: Use `--with-editable .` to install local dependencies
  378. - For manual setup: Run `pip install -r requirements.txt`
  379. - **Permission errors**: Use absolute paths in configuration
  380. - **Environment variables not working**: Verify `.env` file format or `-v` flag syntax
  381. - **Module not found**: Ensure you're using `--with-editable .` flag for local package installation
  382. ### Debugging Steps
  383. **Step 1: Check MCP CLI Status**
  384. ```bash
  385. # List all installed servers
  386. mcp list
  387. # Check specific server status
  388. mcp status "Chrome DevTools MCP"
  389. ```
  390. **Step 2: Test Server Manually**
  391. ```bash
  392. # Test if server starts without errors
  393. python3 server.py
  394. # Test imports
  395. python3 -c "from server import mcp; print(f'Server: {mcp.name}')"
  396. ```
  397. **Step 3: Check Configuration**
  398. **For Claude Desktop:**
  399. ```bash
  400. # View current configuration (macOS)
  401. cat "~/Library/Application Support/Claude/claude_desktop_config.json"
  402. # View current configuration (Windows)
  403. type "%APPDATA%/Claude/claude_desktop_config.json"
  404. ```
  405. **For Claude Code:**
  406. ```bash
  407. # List configured MCP servers
  408. claude mcp list
  409. # Get details about a specific server
  410. claude mcp get chrome-devtools
  411. # IMPORTANT: Verify paths are absolute, not relative
  412. # Good example output:
  413. # Command: /Users/you/chrome-devtools-mcp/.venv/bin/python
  414. # Args: ["/Users/you/chrome-devtools-mcp/server.py"]
  415. # Bad example output:
  416. # Command: python
  417. # Args: ["server.py"]
  418. # Test the exact command Claude Code will use
  419. /path/to/.venv/bin/python /path/to/server.py
  420. # Check if server is working
  421. claude mcp serve --help
  422. ```
  423. **Step 3.5: Fix Path Issues (Claude Code specific)**
  424. ```bash
  425. # If paths are relative, remove and re-add with absolute paths
  426. claude mcp remove chrome-devtools
  427. # Re-add with absolute paths
  428. SERVER_PATH="$(pwd)/server.py"
  429. PYTHON_PATH="$(pwd)/.venv/bin/python"
  430. claude mcp add chrome-devtools "$PYTHON_PATH" "$SERVER_PATH" -e CHROME_DEBUG_PORT=9222
  431. ```
  432. **Step 4: Reinstall if Needed**
  433. **For MCP CLI:**
  434. ```bash
  435. # Clean reinstall
  436. mcp remove "Chrome DevTools MCP"
  437. mcp install server.py -n "Chrome DevTools MCP" --with-editable .
  438. # Restart Claude Desktop completely
  439. ```
  440. **For Claude Code:**
  441. ```bash
  442. # Remove and re-add the server
  443. claude mcp remove chrome-devtools
  444. claude mcp add chrome-devtools python server.py -e CHROME_DEBUG_PORT=9222
  445. # Or update with different scope
  446. claude mcp add chrome-devtools python server.py -s user -e CHROME_DEBUG_PORT=9222
  447. ```
  448. ### Common Error Messages
  449. | Error | Solution |
  450. |-------|----------|
  451. | "Module not found" | Use `--with-editable .` flag |
  452. | "No server object found" | Server should export `mcp` object (already fixed) |
  453. | "Import error" | Check `pip install mcp websockets aiohttp` |
  454. | "Permission denied" | Use absolute paths in config |
  455. | "Server disabled" | Check Claude Desktop logs, restart Claude |
  456. | "python: command not found" (Claude Code) | Use absolute path to venv Python: `/path/to/.venv/bin/python` |
  457. | "server.py: No such file" (Claude Code) | Use absolute path to server: `/path/to/server.py` |
  458. | "ModuleNotFoundError" (Claude Code) | Use venv Python that has dependencies installed |
  459. ### Manual Configuration Fallback
  460. **For Claude Desktop:**
  461. If MCP CLI isn't working, add this to Claude Desktop config manually:
  462. ```json
  463. {
  464. "mcpServers": {
  465. "chrome-devtools": {
  466. "command": "python3",
  467. "args": ["/absolute/path/to/chrome-devtools-mcp/server.py"],
  468. "env": {
  469. "CHROME_DEBUG_PORT": "9222"
  470. }
  471. }
  472. }
  473. }
  474. ```
  475. **For Claude Code:**
  476. If the `claude mcp add` command isn't working, you can use the JSON format with absolute paths:
  477. ```bash
  478. # Get absolute paths first
  479. SERVER_PATH="$(pwd)/server.py"
  480. PYTHON_PATH="$(pwd)/.venv/bin/python"
  481. # Add server using JSON configuration with absolute paths
  482. claude mcp add-json chrome-devtools "{
  483. \"command\": \"$PYTHON_PATH\",
  484. \"args\": [\"$SERVER_PATH\"],
  485. \"env\": {
  486. \"CHROME_DEBUG_PORT\": \"9222\"
  487. }
  488. }"
  489. # Or if you have it working in Claude Desktop, import from there
  490. claude mcp add-from-claude-desktop
  491. ```
  492. **Example of correct Claude Code configuration (with absolute paths):**
  493. ```json
  494. {
  495. "command": "/Users/you/chrome-devtools-mcp/.venv/bin/python",
  496. "args": ["/Users/you/chrome-devtools-mcp/server.py"],
  497. "env": {
  498. "CHROME_DEBUG_PORT": "9222"
  499. }
  500. }
  501. ```
  502. ### Connection Issues
  503. - **Chrome won't start**: The MCP server will start Chrome automatically when you use `start_chrome()`
  504. - **Can't connect**: Try `get_connection_status()` to check the connection
  505. - **Tools not working**: Ensure you've called `connect_to_browser()` or used `start_chrome_and_connect()`
  506. ### Common Misconceptions
  507. - **This is not a web server**: The MCP server runs inside Claude Desktop, not as a separate web service
  508. - **No separate installation needed**: Once configured in Claude Desktop, the server starts automatically
  509. - **Your app runs separately**: This tool connects to your existing web application, it doesn't run it
  510. ## Development & Testing
  511. *This section is for developers who want to test or modify the MCP server itself.*
  512. ### Development Setup
  513. **With uv (recommended):**
  514. ```bash
  515. git clone https://github.com/benjaminr/chrome-devtools-mcp.git
  516. cd chrome-devtools-mcp
  517. uv sync
  518. ```
  519. **With pip:**
  520. ```bash
  521. git clone https://github.com/benjaminr/chrome-devtools-mcp.git
  522. cd chrome-devtools-mcp
  523. pip install -e ".[dev]"
  524. ```
  525. ### Code Quality Tools
  526. ```bash
  527. # Format code
  528. uv run ruff format .
  529. # Lint code
  530. uv run ruff check .
  531. # Type checking
  532. uv run mypy src/
  533. ```
  534. ### Building the Extension
  535. **Install DXT packaging tools:**
  536. ```bash
  537. npm install -g @anthropic-ai/dxt
  538. ```
  539. **Build the extension:**
  540. ```bash
  541. # Quick build
  542. make package
  543. # Or manually
  544. npx @anthropic-ai/dxt pack
  545. ```
  546. **Using Makefile for development:**
  547. ```bash
  548. make help # Show all commands
  549. make install # Install dependencies
  550. make dev # Setup development environment + pre-commit
  551. make check # Run all checks (lint + type + test)
  552. make pre-commit # Run pre-commit hooks manually
  553. make package # Build .dxt extension
  554. make release # Full release build
  555. ```
  556. ### Pre-commit Hooks
  557. This project uses pre-commit hooks to ensure code quality:
  558. - **ruff**: Linting and formatting
  559. - **mypy**: Type checking
  560. - **pytest**: Test validation
  561. - **MCP validation**: Server registration check
  562. Pre-commit hooks run automatically on `git commit` and can be run manually with `make pre-commit`.
  563. ## License
  564. MIT License

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.