MCP Cursor Server

یک MCP Server قدرتمند برای Cursor IDE که امکانات پیشرفته‌ای مثل تحلیل کد، عملیات Git، تست‌نویسی و بیشتر را از طریق cursor-agent CLI فراهم می‌کند.

A powerful MCP (Model Context Protocol) server for Cursor IDE that provides advanced features like code analysis, Git operations, test generation, and more through cursor-agent CLI integration.

✨ Features

• 🔍 Code Analysis: Deep code analysis with metrics and quality indicators
• 🔧 Git Operations: Commit, push, pull, diff, status with conventional commits support
• 🧪 Test Generation: Automatic test generation and execution
• 📁 File Operations: Create, read, write, delete, copy, move files
• 🔎 Code Search: Advanced code search with regex and filtering
• 🤖 AI-Powered: Deep search and code explanation capabilities
• 🎯 Navigation: Go to line, go to symbol, find definitions and usages
• 📦 Workspace Management: Project creation and workspace switching
• 🔌 Extension Management: Install and manage Cursor extensions
• ⚡ Free Prompt Execution: Execute custom operations with safety features

📋 Prerequisites

Before using this MCP server, you need to have cursor-agent CLI installed and configured:

For Linux/macOS:

# Install cursor-agent globally
npm install -g cursor-agent

For Windows:

Important: On Windows, cursor-agent only works through WSL (Windows Subsystem for Linux).

1. Install WSL (if not already installed):

   wsl --install

2. Inside WSL, install cursor-agent:

   wsl
   npm install -g cursor-agent

3. Make sure WSL is accessible from Windows PATH

Note: The MCP server automatically detects Windows and runs cursor-agent through WSL.

🚀 Installation

Method 1: Using NPX (Recommended)

Add to your MCP configuration file (.kiro/settings/mcp.json or ~/.kiro/settings/mcp.json):

{
  "mcpServers": {
    "cursor-mcp": {
      "command": "npx",
      "args": ["-y", "@mmdnzhd/mcp-cursor"]
    }
  }
}

Method 2: Global Installation

npm install -g @mmdnzhd/mcp-cursor

Then in your MCP config:

{
  "mcpServers": {
    "cursor-mcp": {
      "command": "mcp-cursor"
    }
  }
}

🔧 Configuration

The server automatically handles session management and workspace context. No additional configuration is required.

Optional Environment Variables

You can set these environment variables for customization:

{
  "mcpServers": {
    "cursor-mcp": {
      "command": "npx",
      "args": ["-y", "@mmdnzhd/mcp-cursor"],
      "env": {
        "CURSOR_AGENT_TIMEOUT": "120000"
      }
    }
  }
}

📚 Available Tools

Code Analysis

• analyze_code - Analyze code with multiple depth levels
• get_code_issues - Get code issues with filtering and sorting

Git Operations

• git_commit - Commit with conventional commits support
• git_push - Push to remote
• git_pull - Pull from remote
• git_diff - Show differences
• git_status - Show repository status

Testing

• generate_test - Generate tests for files
• run_tests - Execute tests
• get_test_coverage - Get coverage reports

File Operations

• create_file, delete_file, copy_file, move_file
• read_file, write_file

Code Search & Navigation

• search_code - Advanced code search
• find_definition - Find symbol definitions
• find_usages - Find symbol usages
• go_to_line, go_to_symbol - Navigate code

AI-Powered Features

• ai_deep_search - Deep web search across multiple sources
• ai_explain_deep - Comprehensive code explanations

And More!

• Code editing (add function, add class, insert code)
• Terminal integration
• Workspace management
• Extension management
• Free prompt execution with safety features

🎯 Usage Examples

Example 1: Analyze Code

// The MCP client will call:
{
  "tool": "analyze_code",
  "arguments": {
    "filePath": "src/index.ts",
    "analysisLevel": "deep"
  }
}

Example 2: Git Commit with Conventional Commits

{
  "tool": "git_commit",
  "arguments": {
    "message": "feat: add new feature",
    "conventional": true,
    "all": true
  }
}

Example 3: Search Code

{
  "tool": "search_code",
  "arguments": {
    "query": "function.*export",
    "useRegex": true,
    "fileTypes": ["ts", "js"]
  }
}

🏗️ Architecture

This MCP server acts as a bridge between MCP clients (like Kiro, Claude Desktop, etc.) and cursor-agent CLI:

MCP Client → MCP Cursor Server → cursor-agent CLI → Cursor IDE

The server:

1. Receives tool calls from MCP clients
2. Translates them into cursor-agent CLI commands
3. Executes the commands with proper error handling
4. Formats and returns structured responses

🔒 Safety Features

The execute_free_prompt tool includes safety features:

• Safe mode enabled by default
• Blocks dangerous operations
• Protects critical files
• Dry-run mode for previewing changes
• Confirmation requirements for destructive operations

🛠️ Development

Build

npm run build

Run Locally

npm start

Project Structure

mcp-cursor/
├── src/
│   ├── index.ts           # Main server logic
│   ├── cursor-tools.ts    # Tool definitions
│   └── tool-prompts.ts    # Prompt templates
├── build/                 # Compiled output
├── package.json
├── tsconfig.json
└── README.md

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📝 License

MIT License - see LICENSE file for details

🐛 Troubleshooting

cursor-agent not found

On Linux/macOS:

# Check if cursor-agent is available
cursor-agent --version

# If not, install it
npm install -g cursor-agent

On Windows:

# Make sure WSL is installed
wsl --version

# Check cursor-agent inside WSL
wsl cursor-agent --version

# If not found, install inside WSL
wsl
npm install -g cursor-agent
exit

WSL Issues on Windows

If you get "WSL not found" error:

1. Install WSL: wsl --install
2. Restart your computer
3. Open WSL and install Node.js:

   wsl
   curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
   sudo apt-get install -y nodejs
   npm install -g cursor-agent

Permission Issues

On Unix systems, you might need to make the script executable:

chmod +x node_modules/.bin/mcp-cursor

Session Issues

The server maintains sessions per workspace. If you encounter session issues, restart the MCP server.

📞 Support

• NPM Package: @mmdnzhd/mcp-cursor
• Author: mmdnzhd

🙏 Acknowledgments

• Built on Model Context Protocol
• Powered by cursor-agent
• Inspired by the Cursor IDE community

نصب و راه‌اندازی (فارسی)

پیش‌نیازها

برای لینوکس/مک:

npm install -g cursor-agent

برای ویندوز:

مهم: در ویندوز، cursor-agent فقط از طریق WSL کار می‌کند.

1. نصب WSL (اگر نصب نیست):

wsl --install

2. داخل WSL، cursor-agent را نصب کنید:

wsl
npm install -g cursor-agent

نصب

در فایل .kiro/settings/mcp.json یا ~/.kiro/settings/mcp.json:

{
  "mcpServers": {
    "cursor-mcp": {
      "command": "npx",
      "args": ["-y", "@mmdnzhd/mcp-cursor"]
    }
  }
}

استفاده

بعد از نصب، تمام ابزارها از طریق MCP client شما قابل دسترسی هستند.

Made with ❤️ for the Cursor community