# 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):

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

3. **Install the required Python packages**:

   ```bash
   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:

```bash
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:

   ```json
   {
     "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.