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:
-
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:
// 1. Cursor Event (File Change)
// When user types in Cursor:
function calculateTotal(items) {
// Calculate the total price of items| {
return total + (item.price * item.quantity);
}, 0);`
// 5. Cursor Integration
// Bridge injects the code at cursor position
-
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
-
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
-
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)
})
-
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)
})
-
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
# 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
Acknowledgments
