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

Using Multiple MCPs

Custom MCP Integration

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:

Installation

Windows

macOS

Linux

Usage

Basic Usage

Window Management

Input Automation

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

Example Workflow

1. Code Completion Request:
   // 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:
   // 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:
   // 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:
   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:
   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:
   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

Running Tests

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• 📚 Documentation
• 🐛 Issue Tracker
• 💬 Discussions
• 🔒 Security

Acknowledgments

• Cursor Editor - The AI-first code editor
• Claude AI - Advanced AI assistant
• @nut-tree/nut-js - Cross-platform automation
• active-win - Window detection