MCP Cursor Server

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:

$3

``bash

Install cursor-agent globally

npm install -g cursor-agent
`

$3

> 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

$3

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"]
}
}
}
`

$3

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

$3

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

$3

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

$3

- 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

$3

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

$3

- create_file, delete_file, copy_file, move_file
- read_file, write_file

$3

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

$3

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

$3

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

🎯 Usage Examples

$3

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

$3

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

$3

`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

$3

`bash
npm run build
`

$3

`bash
npm start
`

$3

`
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

$3

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
`

$3

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
`

$3

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

`bash
chmod +x node_modules/.bin/mcp-cursor
`

$3

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

---



---

Made with ❤️ for the Cursor community