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

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

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

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:

{
    "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

# 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

# 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

# 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

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

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

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

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
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

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

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 ```

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 ```

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

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) }) ```

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) }) ```

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

# 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

# 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 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

multiplatform-cursor-mcp

Author

johnneerdael

Quick Info

Actions

Tags

Cursor MCP (Model Context Protocol)

Overview

🤖 AI Integration

🔌 MCP Protocol Support

🖥️ Cross-Platform Window Management

⌨️ Input Automation

🔄 Process Management

MCP Integration

Claude Desktop Integration

Using Multiple MCPs

Custom MCP Integration

Configuration

Installation

Windows

macOS

Linux

Usage

Basic Usage

Window Management

Input Automation

How It Works

Bridge Architecture

Example Workflow

Integration Methods

Security

Requirements

Windows

macOS

Linux

Development

Setup

Running Tests

Contributing

License

Support

Acknowledgments

See Also