Search MCP 🔍

Make your AI 58x smarter about your code.

# Navigate to your project, then run:
npx @liraz-sbz/search-mcp setup

Your AI assistant searches your entire codebase semantically. No API keys. No cloud. 100% local.

Works with: Claude Desktop • Claude Code • Cursor • Windsurf • Antigravity

---

Why Search MCP?

Without Search MCP	With Search MCP
Copy-paste files manually	AI finds code automatically
~488,000 tokens per query	~8,400 tokens per query
"Context limit exceeded"	Always fits
Multiple tool calls	Single semantic search

---

Table of Contents

• What Does This Do?
• Features
• Quick Start
• Standalone CLI
• What Can You Ask?
• Performance
• Configuration
• FAQ
• Documentation
• For Developers
• Updating & Uninstalling
• Troubleshooting
• Privacy & License

---

Search MCP makes your AI assistant smarter about your code. Instead of you copying and pasting files into the chat, the AI can automatically search your project and find exactly what it needs.

Before Search MCP:

You: "How does login work?"
AI: "I don't have access to your code. Please paste the relevant files."
You: *pastes 5 files*
AI: "Now I can help..."

After Search MCP:

You: "How does login work?"
AI: *automatically searches your code*
AI: "Based on src/auth/login.ts, here's how login works..."

---

• Just Works - No setup, no API keys, no accounts
• Private - Your code never leaves your computer
• Always Current - Automatically updates when you save files
• Safe - Never indexes passwords, secrets, or junk files
• Secure - Built-in protections against path traversal, symlink attacks, and resource exhaustion

---

Prerequisites: Node.js 18+

Option 1: Interactive Setup (Recommended)

Navigate to your project folder and run:

npx @liraz-sbz/search-mcp setup

This interactive wizard will:

• Confirm you're in the correct project folder
• Auto-detect and configure your AI assistants (Claude Desktop, Claude Code, Cursor, Windsurf)
• Offer to index your project immediately with progress bars

See all CLI commands: CLI Reference

Option 2: Quick Setup (One-liner)

npx --yes @liraz-sbz/search-mcp@latest --setup

Configures your AI assistants automatically. You'll need to index separately via your AI assistant.

Option 3: Manual Configuration

Add to your MCP config file:

{
  "mcpServers": {
    "search": {
      "command": "npx",
      "args": ["-y", "@liraz-sbz/search-mcp"]
    }
  }
}

Config file locations:

• Claude Desktop (Mac): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Claude Code: claude mcp add search -- npx @liraz-sbz/search-mcp

See full guide: Getting Started

After Setup

1. Restart your AI assistant
2. Verify connection: Type /mcp and check that "search" is listed
3. Start searching: Ask "How does login work?"

That's it!

---

Search MCP also works as a standalone CLI tool - no MCP client required:

# Index your project
npx @liraz-sbz/search-mcp index

# Search directly from terminal
npx @liraz-sbz/search-mcp search "authentication logic"

# Check index status
npx @liraz-sbz/search-mcp status

Features:

• Progress bars and colored output
• --json flag for scripting
• Works independently of AI assistants

Perfect for quick searches, debugging, or CI/CD integration.

Full CLI Reference →

---

Once set up, just talk naturally:

• "How does user registration work?"
• "Find all files related to payments"
• "What's the database schema?"
• "Show me where errors are handled"
• "What files import the Logger class?"
• "Search the docs for API rate limits"

See more examples and use cases.

---

Metric	Value
Efficiency vs Grep	58x fewer tokens
Search speed	~400ms (with GPU acceleration)
Tokens per query	~8,400
Codebase tested	306 files, 4,231 chunks

Semantic search returns focused code chunks instead of entire files. Your AI stays under context limits even on large codebases.

Full benchmark details →

---

Config is auto-generated when you first index a project:

• macOS/Linux: ~/.mcp/search/indexes/<project-hash>/config.json
• Windows: %USERPROFILE%\.mcp\search\indexes\<project-hash>\config.json

Finding your config file: Ask your AI assistant "Where is my config file?" or "Show me my search config" - it will use the get_config tool to return the exact path.

Key options:

Option	Default	Description
indexingStrategy	"realtime"	"realtime", "lazy", or "git"
include	["**/*"]	Files to index
exclude	[]	Files to skip
indexDocs	true	Index .md and .txt files separately

Indexing Strategies:

Strategy	Best For
realtime	Small projects, instant freshness
lazy	Large projects, index only when searching
git	Only search committed code

For full configuration options, see the Configuration Reference.

---

Does my code leave my computer? Never. All processing happens locally. No cloud, no API calls, no tracking.

How big can my codebase be? Tested on projects with 1000+ files. Indexing takes ~1 minute for most projects.

What languages are supported? Any text-based code or documentation. The semantic search understands concepts across all languages.

How do I update the index? File changes are detected automatically. Use reindex_project for a full rebuild.

---

Guide	Description
Getting Started	Detailed installation for all clients
CLI Reference	Standalone command-line interface
Configuration	Full config reference + indexing strategies
API Reference	Complete tool documentation
Examples	Use cases & best practices
Troubleshooting	Common issues & solutions
Roadmap	Planned features
Changelog	Version history
Contributing	How to contribute

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│                      MCP CLIENT                             │
│  (Claude Desktop, Claude Code, Cursor, Windsurf, etc.)      │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│                  SEARCH MCP SERVER                          │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌─────────────┐ │
│  │create_    │ │search_code│ │search_by_ │ │get_index_   │ │
│  │index      │ │           │ │path       │ │status       │ │
│  └───────────┘ └───────────┘ └───────────┘ └─────────────┘ │
│  ┌───────────┐ ┌───────────┐ ┌───────────┐                 │
│  │reindex_   │ │reindex_   │ │delete_    │                 │
│  │project    │ │file       │ │index      │                 │
│  └───────────┘ └───────────┘ └───────────┘                 │
└─────────────────────────┬───────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        ▼                 ▼                 ▼
┌───────────────┐ ┌───────────────┐ ┌───────────────┐
│   Chunking    │ │   Embedding   │ │   LanceDB     │
│   Engine      │ │   (BGE)       │ │   (Local)     │
└───────────────┘ └───────────────┘ └───────────────┘

MCP Tools

Tool	Description	Confirmation
create_index	Create a search index for the current project	Yes
search_code	Semantic search for relevant code chunks	No
search_docs	Semantic search for documentation files	No
search_by_path	Find files by name/glob pattern	No
get_index_status	Show index statistics and paths	No
get_config	Get config file path and contents	No
get_file_summary	Extract symbols and complexity metrics from a file	No
reindex_project	Rebuild the entire index	Yes
reindex_file	Re-index a single file	No
delete_index	Remove the project index	Yes

Technical Details

Property	Value
Embedding Models	Code: Xenova/bge-small-en-v1.5 (384d), Docs: Xenova/bge-base-en-v1.5 (768d)
Code Chunk Size	~1000 tokens
Doc Chunk Size	~2000 tokens
Search Latency	< 200ms
Storage	~/.mcp/search/indexes/ (macOS/Linux) or %USERPROFILE%\.mcp\search\indexes\ (Windows)

GPU Acceleration

Search MCP automatically uses GPU acceleration when available for faster indexing:

Platform	GPU Support	Notes
Windows	DirectML	Automatic GPU acceleration on all modern GPUs (NVIDIA, AMD, Intel)
macOS	CPU only	CoreML not available in Node.js bindings
Linux	CPU only	CUDA requires separate package (not included)

GPU Compatibility (Windows):

• NVIDIA: GeForce GTX 1000+, RTX series, Quadro
• AMD: RX 400+, Radeon Pro
• Intel: Arc, UHD/Iris integrated graphics

GPU acceleration is automatic - no configuration needed. The system detects available hardware and selects the best option. Check get_index_status to see which compute device is being used.

Hybrid GPU Laptops (NVIDIA + Intel/AMD integrated):

On laptops with both discrete and integrated GPUs, Search MCP defaults to CPU to avoid DirectML selecting the wrong GPU. To enable GPU acceleration:

1. Open Windows Settings → System → Display → Graphics
2. Click Add an app and select your IDE (VS Code, Cursor, etc.) or terminal
3. Click on the app → Options → Select High performance
4. Set environment variable: FORCE_DML=1

This tells Windows to use your discrete GPU (NVIDIA/AMD) for that application.

For full technical documentation, see ENGINEERING.RFC.md.

---

Updating

If using npx in your config (recommended): Updates are automatic - you always get the latest version.

If installed globally:

npm install -g @liraz-sbz/search-mcp

Uninstalling

1. Remove from your AI assistant:

• Claude Code: claude mcp remove search
• Other clients: Delete the search entry from your MCP config file

2. Uninstall the package (if installed globally):

npm uninstall -g @liraz-sbz/search-mcp

3. (Optional) Remove index data:

• macOS/Linux: rm -rf ~/.mcp/search
• Windows: rmdir /s /q %USERPROFILE%\.mcp\search

---

Common issues:

Issue	Solution
"Index not found"	Say "Index this project" to create the index
MCP connection issues	Run npx --yes @liraz-sbz/search-mcp@latest --setup to reconfigure
Search results seem wrong	Run reindex_project to rebuild
Changes not detected	Run reindex_file for specific file

CLI commands:

npx @liraz-sbz/search-mcp index                # Create/update index
npx @liraz-sbz/search-mcp search "query"       # Search code
npx @liraz-sbz/search-mcp status               # Show index info
npx @liraz-sbz/search-mcp --setup              # Configure MCP clients

See the CLI Reference for all commands and options.

Debug mode: Set DEBUG=1 or SEARCH_MCP_DEBUG=1 environment variable for verbose logging.

For all error codes and solutions, see the Troubleshooting Guide.

---

Your code stays on your computer. Nothing is uploaded anywhere. No accounts, no API keys, no tracking.

MIT License - See LICENSE for details.

---

Getting Help

• GitHub Issues - Report bugs or request features
• Documentation - Full guides and references