cursorx-mcp

cursor-mcp-bridge

🚀 Fully Tested & Production Ready - Enhanced Bridge between Claude Code and Cursor AI for intelligent project consultation through MCP (Model Context Protocol). Complete DOM operations, intelligent waiting mechanisms, and verified end-to-end communication!

🚀 Quick Start

Installation

You don't need to install anything! Just use npx:

npx cursor-mcp-bridge

Configuration

Add to your Claude Code MCP configuration file:

Windows:

{
  "mcpServers": {
    "cursor-project-advisor": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "cursor-mcp-bridge"]
    }
  }
}

Mac/Linux:

{
  "mcpServers": {
    "cursor-project-advisor": {
      "command": "npx",
      "args": ["-y", "cursor-mcp-bridge"]
    }
  }
}

🎛️ Environment Configuration

Customize Cursor analysis behavior:

{
  "mcpServers": {
    "cursor-project-advisor": {
      "command": "npx",
      "args": ["-y", "cursor-mcp-bridge"],
      "env": {
        "CURSOR_MESSAGE_PREFIX": "[Project Analysis Mode] Use Cursor's built-in search and analysis tools first: 1) Search related code files and configs 2) Analyze project architecture and dependencies 3) Provide analysis based on complete understanding. No code modifications, no long code blocks:",
        "CURSOR_MESSAGE_TIMEOUT": "360000"
      }
    }
  }
}

Environment Variables:

• CURSOR_MESSAGE_PREFIX: Customizes the analysis instruction prefix sent to Cursor for project-first analysis approach.
• CURSOR_MESSAGE_TIMEOUT: Request timeout in milliseconds. Default: 360000 (6 minutes). Adjust based on project complexity and network conditions.

Usage in Claude Code

Once configured, you can use the MCP tool in Claude Code:

mcp__cursor-project-advisor__consult("Please analyze the project architecture")

📋 Requirements

• Node.js >= 18.0.0
• Cursor (latest version)
• Claude Code with MCP support

🛠️ CLI Commands

# Start the server (default)
npx cursor-mcp-bridge

# Show help
npx cursor-mcp-bridge help

# Show version
npx cursor-mcp-bridge version

🔧 How It Works (Enhanced Version)

• HTTP Discovery Service: Server starts on port 28765 for script injection and status monitoring
• Dynamic WebSocket Allocation: Automatically finds available ports from multiple ranges (28766-28776, 38766-38776, 48766-48776)
• One-Click Script Injection: Visit http://localhost:28765/inject or use the auto-injection command
• Intelligent Communication: Enhanced client script with DOM operations, button state monitoring, and content stability detection
• Deep Project Analysis: Cursor provides comprehensive project understanding with enhanced message processing

🆕 Enhanced Features

• Smart Button Detection: Automatically detects and clicks New Tab buttons
• Message Completion Intelligence: Advanced waiting mechanisms based on button states and content stability
• HTML Entity Decoding: Proper handling of encoded content from Cursor responses
• Diagnostic Tools: Built-in debugging and status checking capabilities
• Multi-Instance Support: Intelligent port management allows multiple server instances

📝 Features

🎯 Core Features

• Context Auto-expansion: Cursor automatically retrieves and supplements relevant code based on key information
• Deep Project Understanding: Leverages retrieval models to understand entire codebase structure
• Intelligent Association Analysis: Finds related code patterns and potential impacts
• Architecture Consistency: Provides suggestions that align with existing code style
• Configurable Timeouts: Flexible timeout configuration via environment variables for different project needs

🚀 Enhanced Features (v1.2.0)

• Complete DOM Operations: Full-featured element detection, text input, and button clicking
• Intelligent Waiting Systems: Advanced message completion detection using multiple strategies
• Content Stability Monitoring: Ensures responses are fully loaded before extraction
• New Tab Management: Automatic new tab creation with smart button detection
• HTML Entity Processing: Complete decoding of HTML entities in responses
• Dynamic Port Discovery: Automatic port allocation from multiple ranges
• One-Click Injection: HTTP-based script injection for easier setup
• Real-time Diagnostics: Built-in debugging and status monitoring tools

🐛 Troubleshooting

Enhanced Version (v1.2.0)

Script Injection Issues

• Visit http://localhost:28765 to check server status
• Use the one-click injection: fetch('http://localhost:28765/inject').then(r=>r.text()).then(script=>{new Function(script)();})
• Check browser console for any Trusted Types errors

WebSocket Connection Failed

• Enhanced version uses dynamic ports (28766-28776, 38766-38776, 48766-48776)
• Server automatically finds available ports and clears conflicts
• Check http://localhost:28765/status for current port information
• Check firewall settings for port ranges
• Restart both Cursor and Claude Code

Message Processing Issues

• Enhanced version includes content stability detection
• If responses seem incomplete, check the diagnostic tools: window.diagnose()
• Use window.testMessage("test") in Cursor console to verify functionality
• Check for proper copy button detection in message completion

Standard Troubleshooting

MCP Tool Not Available

• Verify the MCP configuration is correct
• Check Node.js version (must be >= 18.0.0)
• Review Claude Code logs for errors

Performance Issues

• Adjust CURSOR_MESSAGE_TIMEOUT environment variable for complex projects
• Enhanced version includes intelligent timeout mechanisms
• Monitor connection status via http://localhost:28765/status

📄 License

MIT

🔗 Links

• GitHub Repository
• Report Issues