Cursor MCP Server

# Cursor MCP (Model Context Protocol) Cursor MCP is a bridge between Claude's desktop application and the Cursor editor, enabling seamless AI-powered automation and multi-instance management. It's part of the broader Model Context Protocol (MCP) ecosystem, allowing Cursor to interact with various AI models and services through standardized interfaces. ## Overview ### 🤖 AI Integration - Direct integration with Claude's desktop application - Ability to leverage other MCP-compatible AI services - Real-time context sharing between AI and editor - AI-powered automation and code generation ### 🔌 MCP Protocol Support - Standardized communication with AI models - Extensible plugin system for additional MCPs - Context-aware command execution - Secure token-based authentication ### 🖥️ Cross-Platform Window Management - Seamlessly manage Cursor editor windows across operating systems - Focus, minimize, restore, and arrange windows programmatically - Track window state changes and positions - Handle multiple Cursor instances simultaneously ### ⌨️ Input Automation - AI-driven keyboard input with support for: - Code generation and insertion - Refactoring operations - Context-aware completions - Multi-cursor editing - Intelligent mouse automation including: - Smart selection - Context-menu operations - AI-guided navigation ### 🔄 Process Management - AI-orchestrated instance management - Smart workspace organization - Automatic context preservation - Intelligent session recovery ## MCP Integration ### Claude Desktop Integration ```typescript import { ClaudeMCP } from 'cursor-mcp/claude' // Connect to Claude's desktop app const claude = await ClaudeMCP.connect() // Execute AI-powered operations await claude.generateCode({ prompt: 'Create a React component', context: currentFileContent, language: 'typescript' }) // Get AI suggestions const suggestions = await claude.getSuggestions({ code: selectedText, type: 'refactor' }) ``` ### Using Multiple MCPs ```typescript import { MCPRegistry } from 'cursor-mcp/registry' // Register available MCPs MCPRegistry.register('claude', ClaudeMCP) MCPRegistry.register('github-copilot', CopilotMCP) // Use different AI services const claude = await MCPRegistry.get('claude') const copilot = await MCPRegistry.get('github-copilot') // Compare suggestions const claudeSuggestions = await claude.getSuggestions(context) const copilotSuggestions = await copilot.getSuggestions(context) ``` ### Custom MCP Integration ```typescript import { BaseMCP, MCPProvider } from 'cursor-mcp/core' class CustomMCP extends BaseMCP implements MCPProvider { async connect() { // Custom connection logic } async generateSuggestions(context: CodeContext) { // Custom AI integration } } // Register custom MCP MCPRegistry.register('custom-ai', CustomMCP) ``` ## Configuration The tool can be configured through environment variables or a config file at: - Windows: `%LOCALAPPDATA%\cursor-mcp\config\config.json` - macOS: `~/Library/Application Support/cursor-mcp/config/config.json` - Linux: `~/.config/cursor-mcp/config.json` Example configuration: ```json { "mcp": { "claude": { "enabled": true, "apiKey": "${CLAUDE_API_KEY}", "contextWindow": 100000 }, "providers": { "github-copilot": { "enabled": true, "auth": "${GITHUB_TOKEN}" } } }, "autoStart": true, "maxInstances": 4, "windowArrangement": "grid", "logging": { "level": "info", "file": "cursor-mcp.log" } } ``` ## Installation ### Windows ```powershell # Run as Administrator Invoke-WebRequest -Uri "https://github.com/your-org/cursor-mcp/releases/latest/download/cursor-mcp-windows.zip" -OutFile "cursor-mcp.zip" Expand-Archive -Path "cursor-mcp.zip" -DestinationPath "." .\windows.ps1 ``` ### macOS ```bash # Run with sudo curl -L "https://github.com/your-org/cursor-mcp/releases/latest/download/cursor-mcp-macos.zip" -o "cursor-mcp.zip" unzip cursor-mcp.zip sudo ./macos.sh ``` ### Linux ```bash # Run with sudo curl -L "https://github.com/your-org/cursor-mcp/releases/latest/download/cursor-mcp-linux.zip" -o "cursor-mcp.zip" unzip cursor-mcp.zip sudo ./linux.sh ``` ## Usage ### Basic Usage ```typescript import { CursorInstanceManager } from 'cursor-mcp' // Get the instance manager const manager = CursorInstanceManager.getInstance() // Start a new Cursor instance await manager.startNewInstance() // Get all running instances const instances = await manager.getRunningInstances() // Focus a specific instance await manager.focusInstance(instances[0]) // Close all instances await manager.closeAllInstances() ``` ### Window Management ```typescript import { WindowManager } from 'cursor-mcp' const windowManager = WindowManager.getInstance() // Find all Cursor windows const windows = await windowManager.findCursorWindows() // Focus a window await windowManager.focusWindow(windows[0]) // Arrange windows side by side await windowManager.arrangeWindows(windows, 'sideBySide') // Minimize all windows for (const window of windows) { await windowManager.minimizeWindow(window) } ``` ### Input Automation ```typescript import { InputAutomationService } from 'cursor-mcp' const inputService = InputAutomationService.getInstance() // Type text await inputService.typeText('Hello, World!') // Send keyboard shortcuts if (process.platform === 'darwin') { await inputService.sendKeys(['command', 'c']) } else { await inputService.sendKeys(['control', 'c']) } // Mouse operations await inputService.moveMouse(100, 100) await inputService.mouseClick('left') await inputService.mouseDrag(100, 100, 200, 200) ``` ## How It Works ### Bridge Architecture This tool acts as a middleware layer between Cursor and MCP servers: 1. **Cursor Integration**: - Monitors Cursor's file system events - Captures editor state and context - Injects responses back into the editor - Manages window and process automation 2. **MCP Protocol Translation**: - Translates Cursor's internal events into MCP protocol messages - Converts MCP responses into Cursor-compatible actions - Maintains session state and context - Handles authentication and security 3. **Server Communication**: - Connects to Claude's desktop app MCP server - Routes requests to appropriate AI providers - Manages concurrent connections to multiple MCPs - Handles fallbacks and error recovery ```mermaid graph LR A[Cursor Editor] <--> B[Cursor MCP Bridge] B <--> C[Claude Desktop MCP] B <--> D[GitHub Copilot MCP] B <--> E[Custom AI MCPs] ``` ### Example Workflow 1. **Code Completion Request**: ```typescript // 1. Cursor Event (File Change) // When user types in Cursor: function calculateTotal(items) { // Calculate the total price of items| <-- cursor position // 2. Bridge Translation const event = { type: 'completion_request', context: { file: 'shopping-cart.ts', line: 2, prefix: '// Calculate the total price of items', language: 'typescript', cursor_position: 43 } } // 3. MCP Protocol Message await mcpServer.call('generate_completion', { prompt: event.context, max_tokens: 150, temperature: 0.7 }) // 4. Response Translation // Bridge converts MCP response: const response = `return items.reduce((total, item) => { return total + (item.price * item.quantity); }, 0);` // 5. Cursor Integration // Bridge injects the code at cursor position ``` 2. **Code Refactoring**: ```typescript // 1. Cursor Event (Command) // User selects code and triggers refactor command const oldCode = ` if (user.age >= 18) { if (user.hasLicense) { if (car.isAvailable) { rentCar(user, car); } } } ` // 2. Bridge Translation const event = { type: 'refactor_request', context: { selection: oldCode, command: 'simplify_nesting' } } // 3. MCP Protocol Message await mcpServer.call('refactor_code', { code: event.context.selection, style: 'simplified', maintain_logic: true }) // 4. Response Translation const response = ` const canRentCar = user.age >= 18 && user.hasLicense && car.isAvailable; if (canRentCar) { rentCar(user, car); } ` // 5. Cursor Integration // Bridge replaces selected code ``` 3. **Multi-File Context**: ```typescript // 1. Cursor Event (File Dependencies) // When user requests help with a component // 2. Bridge Translation const event = { type: 'context_request', files: { 'UserProfile.tsx': '...', 'types.ts': '...', 'api.ts': '...' }, focus_file: 'UserProfile.tsx' } // 3. MCP Protocol Message await mcpServer.call('analyze_context', { files: event.files, primary_file: event.focus_file, analysis_type: 'component_dependencies' }) // 4. Response Processing // Bridge maintains context across requests ``` ### Integration Methods 1. **File System Monitoring**: ```typescript import { FileSystemWatcher } from 'cursor-mcp/watcher' const watcher = new FileSystemWatcher({ paths: ['/path/to/cursor/workspace'], events: ['change', 'create', 'delete'] }) watcher.on('change', async (event) => { const mcpMessage = await bridge.translateEvent(event) await mcpServer.send(mcpMessage) }) ``` 2. **Window Integration**: ```typescript import { CursorWindow } from 'cursor-mcp/window' const window = new CursorWindow() // Inject AI responses await window.injectCode({ position: cursorPosition, code: mcpResponse.code, animate: true // Smooth typing animation }) // Handle user interactions window.onCommand('refactor', async (selection) => { const mcpMessage = await bridge.createRefactorRequest(selection) const response = await mcpServer.send(mcpMessage) await window.applyRefactoring(response) }) ``` 3. **Context Management**: ```typescript import { ContextManager } from 'cursor-mcp/context' const context = new ContextManager() // Track file dependencies await context.addFile('component.tsx') await context.trackDependencies() // Maintain conversation history context.addMessage({ role: 'user', content: 'Refactor this component' }) // Send to MCP server const response = await mcpServer.send({ type: 'refactor', context: context.getFullContext() }) ``` ## Security - Secure token-based authentication for AI services - Encrypted communication channels - Sandboxed execution environment - Fine-grained permission controls ## Requirements ### Windows - Windows 10 or later - Node.js 18 or later - Administrator privileges for installation ### macOS - macOS 10.15 (Catalina) or later - Node.js 18 or later - Xcode Command Line Tools - Accessibility permissions for Terminal ### Linux - X11 display server - Node.js 18 or later - xdotool - libxtst-dev - libpng++-dev - build-essential ## Development ### Setup ```bash # Clone the repository git clone https://github.com/your-org/cursor-mcp.git cd cursor-mcp # Install dependencies npm install # Build the project npm run build # Run tests npm test ``` ### Running Tests ```bash # Run all tests npm test # Run specific test suite npm test -- window-management # Run with coverage npm run test:coverage ``` ## Contributing We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details. ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details. ## Support - 📚 [Documentation](https://your-org.github.io/cursor-mcp) - 🐛 [Issue Tracker](https://github.com/your-org/cursor-mcp/issues) - 💬 [Discussions](https://github.com/your-org/cursor-mcp/discussions) - 🔒 [Security](SECURITY.md) ## Acknowledgments - [Cursor Editor](https://cursor.sh) - The AI-first code editor - [Claude AI](https://anthropic.com/claude) - Advanced AI assistant - [@nut-tree/nut-js](https://github.com/nut-tree/nut-js) - Cross-platform automation - [active-win](https://github.com/sindresorhus/active-win) - Window detection