Cursor MCP Server – AI Coding Assistant for Claude Desktop

Turn Claude Desktop into a Cursor‑like assistant that can browse, search, edit, lint, format, and version‑control your entire codebase – all through a single MCP server.

Directory Tree cursor-mcp-server/ ├── README.md ├── .gitignore ├── requirements.txt ├── mcp_server.py # main server – entry point ├── config.py # global configuration ├── tools/ │ ├── init.py │ ├── file_tools.py # file read/write/diff/tree │ ├── search_tools.py # grep, semantic search, find files │ ├── command_tools.py # safe command execution │ ├── git_tools.py # git status/diff/log/branch │ ├── code_quality_tools.py # linting & formatting │ └── rag.py # ChromaDB indexing & semantic search └── claude_desktop_config.json # ready-to-paste configuration

🚀 Overview

This project provides a Model Context Protocol (MCP) server written in Python. Once connected to Claude Desktop, it gives Claude the ability to:

• Explore the file tree and read/write files
• Search code with regex (grep) and semantic search (ChromaDB + embeddings)
• Apply unified diffs safely (with optional backups)
• Run terminal commands inside the project (sandboxed)
• Inspect Git status, diff, log, and branch
• Lint and format code (detects Python / JavaScript projects)
• Build and query a semantic code index (fully local)

Everything runs offline after installing dependencies – no API keys needed.

📋 Prerequisites

• Python 3.10 or higher
• pip (Python package manager)
• Git (optional, for Git‑related tools)
• Linters / formatters are optional – the tools will detect them if installed:
  • Python: flake8 and black
  • JavaScript/TypeScript: eslint and prettier

📦 Installation

1. Clone or download this repository into a directory of your choice.

2. Create and activate a virtual environment (recommended):

   python3 -m venv .venv
   source .venv/bin/activate
   

3. Install the required Python packages:

   pip install -r requirements.txt
   

   Note: The first time you run the semantic search tools, sentence-transformers will download a small embedding model (~80 MB). This is only needed once and works completely offline afterwards.

⚙️ Setup

1. Build the semantic code index (recommended)

The semantic search tool needs an index. You can build it by running the server and calling the rebuild_index tool, or by running the indexing script manually:

python -m tools.rag

This will walk the entire project, chunk files, and store embeddings inside .chroma_db/.

2. Configure Claude Desktop

1. Open Claude Desktop settings:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Replace or merge the mcpServers section with the content of claude_desktop_config.json from this project. Edit the paths to match your setup:

   {
     "mcpServers": {
       "cursor-assistant": {
         "command": "/path/to/your/project/.venv/bin/python3",
         "args": [
           "/path/to/your/project/mcp_server.py",
           "--project-root",
           "/path/to/your/project"
         ],
         "env": {
           "PROJECT_ROOT": "/path/to/your/project",
           "PYTHONPATH": "/path/to/your/project"
         }
       }
     }
   }
   

   • Replace /path/to/your/project with the absolute path to the project you want to work on.
   • The command should point to the Python binary inside your virtual environment.

3. Restart Claude Desktop completely (quit and reopen).

Once restarted, you’ll see an integration named cursor-assistant. Enable it and start using the assistant.

🧠 Usage

• In Claude Desktop, start a conversation. The tools are automatically available.
• You can ask in natural language:
  • “Show me the file tree”
  • “Find where authentication logic is”
  • “Search for all places where we use the requests library”
  • “Apply this diff to login.py”
  • “What’s the git status?”
  • “Run tests and show me the output”

All destructive actions (writing files, running commands) are described clearly. Always review the proposed actions before Claude executes them. You have full control.

🔧 Tools Reference

Workspace

• get_workspace_info – project root and top‑level entries

Files

• read_file(path) – read a file
• read_multiple_files(paths) – read several files at once
• write_file(path, content) – overwrite/create a file ⚠️
• list_directory(path=".") – list non‑hidden contents
• get_file_tree(path=".", max_depth=4) – recursive tree as JSON
• apply_diff(path, diff, create_backup=True) – apply a unified diff

Search

• grep(pattern, path=".", include=None) – regex search (respects .gitignore)
• semantic_search(query, n_results=5) – semantic (embedding‑based) search
• find_files(pattern, path=".") – glob‑based file search

Commands

• execute_command(command, cwd=".") – run a shell command (⚠️ use with approval)

Git

• git_status() – short status
• git_diff(staged=False) – working directory diff
• git_log(max_count=10) – recent commits
• git_branch() – current branch name

Code Quality

• lint_file(path, linter="auto") – run flake8/eslint
• format_file(path) – run black/prettier (returns formatted code, does not write)

Indexing

• rebuild_index() – rebuild the semantic search index

🛡️ Safety

• All file and command operations are restricted to the project root – path traversal is blocked.
• write_file and apply_diff modify files. Always review the changes before approving.
• execute_command runs in a sandboxed directory, but the command itself is not restricted. Claude will ask for your confirmation before calling this tool.
• Backups are automatically created when applying diffs (can be disabled).

🔍 Offline Capabilities

• Semantic search uses a local embedding model (all-MiniLM-L6-v2) via sentence-transformers. The model is downloaded automatically on first use.
• ChromaDB storage is local (.chroma_db/ folder).
• No internet connection is required after the initial model download and dependency installation.

🐛 Troubleshooting

• “Module not found: mcp” – Ensure you are using the Python from your virtual environment and have run pip install -r requirements.txt inside it.
• rebuild_index fails / semantic search returns nothing – Ensure the .chroma_db/ folder is writable and that sentence-transformers is installed.
• Git tools error – Make sure Git is installed and the project is a Git repository.
• Linter / formatter not found – Install the required tools (e.g., pip install flake8 black, npm install -g eslint prettier) or simply ignore those tools.
• Path outside project root – You may be trying to access a file outside the configured project root. Adjust PROJECT_ROOT.
• Server disconnects immediately – Check the Claude Desktop logs for error messages. A common fix is to run the server manually (python3 mcp_server.py --project-root .) and see the traceback.

📝 License

https://github.com/tariqnasheed – use it, modify it, share it.