leobrival/web-inspector-mcp

🔧 Web Inspector MCP

Unified MCP server for web debugging and performance monitoring with background commands integration

Replace browser-tools-mcp with a single, powerful, and automated web inspection solution that integrates seamlessly with Claude Code's background commands.

✨ Features

• 🔄 Continuous monitoring with Claude Code background commands
• 🚫 Zero configuration - works out of the box
• 📊 Real-time dashboard with WebSocket updates
• 🎯 All browser-tools-mcp features in one package
• 🔧 Auto-installation with interactive CLI
• ⚡ Performance optimized - single process vs multiple components

🚀 Quick Start

One-command installation:

npx web-inspector-mcp --install

This will:

• ✅ Create and configure Chrome extension
• ✅ Add MCP server to your Claude Code config
• ✅ Set up auto-start scripts in your project
• ✅ Install all dependencies

Manual installation:

# Install globally
npm install -g web-inspector-mcp

# Or use npx (recommended)
npx web-inspector-mcp --help

📋 Installation Options

# Full installation (recommended)
npx web-inspector-mcp --install

# Install without MCP configuration
npx web-inspector-mcp --install --no-mcp

# Install without Chrome extension
npx web-inspector-mcp --install --no-extension

# Install with auto-start scripts
npx web-inspector-mcp --install --auto-start

🎯 Usage

With Claude Code (Recommended)

Start monitoring in background mode:

# In your project directory
pnpm dev:monitored
# Or if auto-start was configured:
pnpm dev

Use Ctrl+b when Claude suggests monitoring commands for continuous background operation.

Standalone Usage

# Start MCP server
npx web-inspector-mcp

# Start background monitoring
npx web-inspector-mcp monitor

# Open dashboard
npx web-inspector-mcp dashboard

# Check status
npx web-inspector-mcp status

🔧 MCP Tools Available

Core Monitoring Tools

• start_monitoring - Start continuous web monitoring
• stop_monitoring - Stop monitoring
• get_console_logs - Retrieve console errors/warnings/logs
• get_performance_metrics - Get Core Web Vitals and performance data
• run_accessibility_audit - Run accessibility analysis
• capture_network_logs - Analyze network requests
• get_dashboard_url - Get real-time dashboard URL
• health_check - System status and health

Example with Claude Code:

You: Start monitoring my development site
Claude: I'll start web monitoring for you.
[Uses start_monitoring tool with background mode]
🚀 Web monitoring started for: http://localhost:3000
📊 Dashboard: http://localhost:3002
💡 Tip: This is running in background mode for continuous monitoring

📊 Dashboard

Access the real-time dashboard at: http://localhost:3002

Features:

• 📋 Live console logs
• ⚡ Performance metrics
• ♿ Accessibility issues
• 🌐 Network requests
• 📈 Trending analysis

API Endpoints:

• /api/status - System status
• /api/console - Console logs feed
• /api/performance - Performance metrics
• /api/accessibility - Accessibility audit results

🔧 Configuration

Environment Variables

WEB_INSPECTOR_URL=http://localhost:3000          # Target URL to monitor
WEB_INSPECTOR_PORT=3001                          # MCP server port  
WEB_INSPECTOR_DASHBOARD_PORT=3002                # Dashboard port

MCP Configuration

After installation, your ~/.claude/mcp.json will include:

{
  "mcpServers": {
    "web-inspector": {
      "command": "npx",
      "args": ["web-inspector-mcp"],
      "env": {
        "WEB_INSPECTOR_PORT": "3001",
        "WEB_INSPECTOR_DASHBOARD_PORT": "3002"
      }
    }
  }
}

🆚 vs browser-tools-mcp

🐛 Troubleshooting

Chrome Extension Not Working

# Reinstall extension
npx web-inspector-mcp --install --no-mcp

# Check extension in Chrome
# chrome://extensions/ → Enable "Developer mode" → Load unpacked extension
# Select: ~/.web-inspector-mcp/chrome-extension/

MCP Server Not Responding

# Check status
npx web-inspector-mcp status

# Restart monitoring
npx web-inspector-mcp monitor

# Check Claude Code MCP config
cat ~/.claude/mcp.json

Port Conflicts

# Use different ports
WEB_INSPECTOR_PORT=3005 WEB_INSPECTOR_DASHBOARD_PORT=3006 npx web-inspector-mcp

Background Process Management

# List running processes
ps aux | grep web-inspector

# Kill specific process
pkill -f web-inspector-mcp

# Or use Claude Code to manage background processes

🔧 Development

Project Structure

web-inspector-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── cli.ts                # Installation CLI
│   ├── monitor.ts            # Web monitoring logic
│   ├── background-monitor.ts # Background monitoring
│   ├── dashboard/
│   │   └── server.ts         # Dashboard server
│   └── types/
│       └── index.ts          # TypeScript types
├── chrome-extension/         # Auto-generated Chrome extension
├── package.json
└── README.md

Local Development

# Clone repository
git clone https://github.com/yourusername/web-inspector-mcp.git
cd web-inspector-mcp

# Install dependencies
npm install

# Build
npm run build

# Development mode
npm run dev

# Test installation
npm run cli -- --install

📝 Contributing

1. Fork the repository
2. Create your feature branch: git checkout -b feature/amazing-feature
3. Commit your changes: git commit -m 'Add amazing feature'
4. Push to the branch: git push origin feature/amazing-feature
5. Open a Pull Request

📄 License

MIT License - see file for details

🙏 Acknowledgments

• Inspired by browser-tools-mcp
• Built for Claude Code integration
• Powered by Model Context Protocol

🔗 Links

• Claude Code Documentation
• MCP Specification
• Background Commands Guide

Made with ❤️ for the Claude Code community