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