npm package: @mmdnzhd/mcp-cursor
Description: MCP server for Cursor IDE integration - provides AI-powered code analysis, Git operations, testing, and more via cursor-agent CLI
Author: mmdnzhd
Latest version: 2.0.1

# MCP Cursor Server

<div dir="rtl">

یک MCP Server قدرتمند برای Cursor IDE که امکانات پیشرفته‌ای مثل تحلیل کد، عملیات Git، تست‌نویسی و بیشتر را از طریق cursor-agent CLI فراهم می‌کند.

</div>

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:
```bash
# 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):
   ```bash
   wsl --install
   ```

2. **Inside WSL**, install cursor-agent:
   ```bash
   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`):

```json
{
  "mcpServers": {
    "cursor-mcp": {
      "command": "npx",
      "args": ["-y", "@mmdnzhd/mcp-cursor"]
    }
  }
}
```

### Method 2: Global Installation

```bash
npm install -g @mmdnzhd/mcp-cursor
```

Then in your MCP config:

```json
{
  "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:

```json
{
  "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

```typescript
// The MCP client will call:
{
  "tool": "analyze_code",
  "arguments": {
    "filePath": "src/index.ts",
    "analysisLevel": "deep"
  }
}
```

### Example 2: Git Commit with Conventional Commits

```typescript
{
  "tool": "git_commit",
  "arguments": {
    "message": "feat: add new feature",
    "conventional": true,
    "all": true
  }
}
```

### Example 3: Search Code

```typescript
{
  "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

```bash
npm run build
```

### Run Locally

```bash
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:**
```bash
# Check if cursor-agent is available
cursor-agent --version

# If not, install it
npm install -g cursor-agent
```

**On Windows:**
```bash
# 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:
   ```bash
   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:

```bash
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](https://www.npmjs.com/package/@mmdnzhd/mcp-cursor)
- Author: mmdnzhd

## 🙏 Acknowledgments

- Built on [Model Context Protocol](https://modelcontextprotocol.io/)
- Powered by [cursor-agent](https://cursor.sh/)
- Inspired by the Cursor IDE community

---

<div dir="rtl">

## نصب و راه‌اندازی (فارسی)

### پیش‌نیازها

**برای لینوکس/مک:**
```bash
npm install -g cursor-agent
```

**برای ویندوز:**
> **مهم**: در ویندوز، cursor-agent فقط از طریق WSL کار می‌کند.

1. نصب WSL (اگر نصب نیست):
```bash
wsl --install
```

2. داخل WSL، cursor-agent را نصب کنید:
```bash
wsl
npm install -g cursor-agent
```

### نصب
در فایل `.kiro/settings/mcp.json` یا `~/.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "cursor-mcp": {
      "command": "npx",
      "args": ["-y", "@mmdnzhd/mcp-cursor"]
    }
  }
}
```

### استفاده
بعد از نصب، تمام ابزارها از طریق MCP client شما قابل دسترسی هستند.

</div>

---

Made with ❤️ for the Cursor community