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.