🧠 Supercharge Cursor IDE with Chrome DevTools MCP — Real Browser Debugging for Your AI Assistant
Connect Cursor IDE directly to Chrome DevTools via MCP.
Give your AI assistant real eyes — inspect live DOMs, capture network traces, run Lighthouse audits, and debug performance issues without ever leaving Cursor.
Why This Matters
Cursor IDE is powerful, but until now it’s been blind to the running browser.
By integrating the Chrome DevTools MCP server, you connect Cursor’s Model Context Protocol directly to the Chrome DevTools Protocol — the same interface Chrome engineers use.
This lets your AI assistant:
- Debug live pages
- Inspect DOM and styles
- Capture console logs and network requests
- Run Lighthouse audits and Core Web Vitals
- Test responsive layouts and accessibility
Before MCP: static code reasoning.
After MCP: real-time browser debugging.
🚀 Easiest Install (Cursor Does It for You)
If you’re using Cursor IDE, you can simply ask Cursor to install & configure the Chrome DevTools MCP. Cursor will do the heavy lifting as long as you grant Full Disk Access (macOS) and provide the DevTools MCP package link.
Paste this in Cursor chat:
“Install the **Chrome DevTools MCP* and enable it for me.
Grant any required permissions.
Use the official package chrome-devtools-mcp and add it to my MCP servers.
If needed, updatesettings.json
and restart Cursor.”*
- On macOS, ensure System Settings → Privacy & Security → Full Disk Access → Cursor = ON.
- Cursor will install the MCP and wire up your
settings.json
. - You can immediately run DevTools commands (see prompts below).
Don’t want to grant Full Disk Access? No problem — use the Manual Setup below.
⚙️ Manual Setup (no Full Disk Access)
Prereqs
- Node.js v20+
- npm
- Cursor IDE v1.7.38+
- Chrome (stable/beta/dev/canary)
Where is settings.json
on each OS?
OS | Path to settings.json
|
---|---|
macOS | ~/Library/Application Support/Cursor/User/settings.json |
Windows |
%APPDATA%\Cursor\User\settings.json (usually C:\Users\<you>\AppData\Roaming\Cursor\User\settings.json ) |
Linux | ~/.config/Cursor/User/settings.json |
If the
User
folder orsettings.json
doesn’t exist, create them.
1️⃣ Install the DevTools MCP server (manual)
npm install -g chrome-devtools-mcp
chrome-devtools-mcp --version
2️⃣ Configure Cursor (manual)
Edit your Cursor settings:
{
"mcpServers": {
"chrome-devtools": {
"command": "chrome-devtools-mcp",
"args": []
}
}
}
Alternative (auto-updating):
{
"mcpServers": {
"chrome-devtools": {
"command": "npx",
"args": ["-y", "chrome-devtools-mcp@latest"]
}
}
}
3️⃣ Restart Cursor (manual)
Cursor will now launch Chrome on demand.
🧰 Tools
You can quickly open your Cursor settings file using:
macOS/Linux: ./tools/edit-settings.sh
Windows: ./tools/edit-settings.ps1
These scripts detect your OS path and open or create the settings.json file for editing.
💡 Example Prompts to Try
“Check performance metrics for https://myapp.com
and suggest improvements.”
“Debug https://example.com
for accessibility issues.”
“Take a mobile screenshot and highlight layout shifts.”
“Analyze network requests for https://github.com.”
Cursor will spin up Chrome, run DevTools commands, and return structured results.
⚡ Why This Is More Feature-Rich Than browser-tools-mcp
The open-source browser-tools-mcp proved the concept, but it’s a lightweight Puppeteer wrapper.
This integration is the full Chrome DevTools Protocol, supported by the Chrome DevTools team themselves.
| Capability | BrowserTools MCP | Chrome DevTools MCP |
| ---------------------------- | ----------------- | ----------------------------- |
| Maintainer | Community | Official Chrome DevTools Team |
| Protocol | Puppeteer wrapper | Full DevTools Protocol |
| Network tracing | ❌ | ✅ |
| Lighthouse / Core Web Vitals | ❌ | ✅ |
| Console logs / JS errors | ❌ | ✅ |
| Accessibility audit | ❌ | ✅ |
| Responsive testing | Basic | Advanced |
| Stability | ⚠️ | 💪 Production-ready |
You’re not just opening a page — you’re debugging it live.
🔬 Advanced Config
OS note: The settings.json location differs by OS (see table above).
Edit that file and restart Cursor after changes.
{
"mcpServers": {
"chrome-devtools": {
"command": "chrome-devtools-mcp",
"args": ["--channel", "canary", "--viewport", "1280x720", "--headless"]
}
}
}
Options:
--channel (stable/beta/dev/canary)
--viewport (e.g., 1280x720)
--headless (CI-friendly)
--browserUrl (attach to existing instance)
🤖 Let Cursor Create the GitHub Repo for You
If you want Cursor to create the public GitHub repo from this zip and push it for you, paste this in Cursor chat:
“Create a new public GitHub repository named chrome-devtools-mcp-cursor-guide.
Unzip the attached archive and initialise a git repo.
Add all files, create an initial commit, and push to GitHub (main branch).
Add topics: cursor, chrome-devtools, mcp, ai-development, web-performance.
Then reply with the repo URL.”
🧠 Security Note
The MCP exposes browser internals to the AI assistant.
Use isolated Chrome profiles, avoid authenticated sessions, and treat this as a real debugging bridge.
📦 Repository
👉 chrome-devtools-mcp-cursor-guide on GitHub
Includes:
Example settings.json
Prompts library
Headless CI scripts
Issue templates & workflow
Helper tools for all OSes
🚀 Conclusion
This integration turns Cursor into a true AI debugger:
Real browser context
Performance + accessibility insights
Live DOM and console inspection
Visual testing & network analysis
It’s production-ready, developer-tested, and free.
Cursor with Chrome Devtools MCP Integration by Oliver Chapple
— expanding Cursor’s capabilities for modern AI-assisted web development.
Top comments (0)