MCP Codebase Index Server

AI-powered semantic search for your codebase in Claude Desktop

A Model Context Protocol (MCP) server that enables Claude to search and understand your codebase using Google's Gemini embeddings and Qdrant Cloud vector storage.

✨ Features

• 🔍 Semantic Search: Find code by meaning, not just keywords
• 🎯 Smart Chunking: Automatically splits code into logical functions/classes
• 🔄 Real-time Watch: Monitors file changes and updates index automatically
• 🌐 Multi-language: Supports 15+ programming languages
• ☁️ Cloud Storage: Uses Qdrant Cloud for persistent vector storage
• 📦 Simple Setup: Just 4 environment variables to get started

🚀 Quick Start

Prerequisites

1. Gemini API Key: Get free at Google AI Studio
2. Qdrant Cloud Account: Sign up free at cloud.qdrant.io

Installation

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "codebase": {
      "command": "npx",
      "args": ["-y", "@ngotaico/mcp-codebase-index"],
      "env": {
        "REPO_PATH": "/absolute/path/to/your/project",
        "GEMINI_API_KEY": "AIzaSyC...",
        "QDRANT_URL": "https://your-cluster.gcp.cloud.qdrant.io:6333",
        "QDRANT_API_KEY": "eyJhbGci..."
      }
    }
  }
}

All 4 variables are required:

Variable	Where to Get	Example
REPO_PATH	Absolute path to your project	/Users/you/Projects/myapp
GEMINI_API_KEY	Google AI Studio	AIzaSyC...
QDRANT_URL	Qdrant Cloud cluster URL	https://xxx.gcp.cloud.qdrant.io:6333
QDRANT_API_KEY	Qdrant Cloud API key	eyJhbGci...

Restart Claude Desktop

The server will automatically:

1. Connect to your Qdrant Cloud cluster
2. Create a collection (if needed)
3. Index your entire codebase
4. Watch for file changes

📖 Usage

Ask Claude to search your codebase:

"Find the authentication logic"
"Show me how database connections are handled"  
"Where is error logging implemented?"
"Find all API endpoint definitions"

🎛️ Configuration

Required Variables

{
  "env": {
    "REPO_PATH": "/Users/you/Projects/myapp",
    "GEMINI_API_KEY": "AIzaSyC...",
    "QDRANT_URL": "https://xxx.gcp.cloud.qdrant.io:6333",
    "QDRANT_API_KEY": "eyJhbGci..."
  }
}

Optional Variables

{
  "env": {
    "QDRANT_COLLECTION": "my_project",
    "WATCH_MODE": "true",
    "BATCH_SIZE": "50"
  }
}

Variable	Default	Description
QDRANT_COLLECTION	codebase	Collection name in Qdrant
WATCH_MODE	true	Auto-update on file changes
BATCH_SIZE	50	Embedding batch size

🔧 Setup Guides

• SETUP.md - Detailed setup walkthrough
• QDRANT_CLOUD_SETUP.md - Get Qdrant credentials
• QUICK_REF.md - Quick reference card

🌍 Supported Languages

Python • TypeScript • JavaScript • Dart • Go • Rust • Java • Kotlin • Swift • Ruby • PHP • C • C++ • C# • Shell • SQL • HTML • CSS

📝 How It Works

┌─────────────┐
│  Your Code  │
└──────┬──────┘
       │
       ▼
┌─────────────────┐
│  File Watcher   │  Monitors changes
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Code Parser    │  Splits into chunks
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Gemini API     │  Creates embeddings
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Qdrant Cloud   │  Stores vectors
└──────┬──────────┘
       │
       ▼
┌─────────────────┐
│  Claude Search  │  Semantic queries
└─────────────────┘

🐛 Troubleshooting

Server not appearing in Claude?

Check Claude logs:

tail -f ~/Library/Logs/Claude/mcp*.log

Common issues:

• ❌ REPO_PATH must be absolute path
• ❌ All 4 env variables must be set
• ❌ Qdrant URL must include :6333 port
• ❌ Gemini API key must be valid

Can't connect to Qdrant?

Test connection:

curl -H "api-key: YOUR_KEY" \
  https://YOUR_CLUSTER.gcp.cloud.qdrant.io:6333/collections

Should return JSON with collections list.

Indexing too slow?

• Large repos (1000+ files) take 5-10 minutes initially
• Reduce BATCH_SIZE if hitting rate limits
• Check Gemini API quota: aistudio.google.com

📊 Performance

• Embedding speed: ~100 chunks/minute (Gemini API)
• Search latency: <100ms (Qdrant Cloud)
• Storage: ~1KB per code chunk
• Recommended: <10K chunks per collection

📄 License

MIT © NgoTaiCo

🤝 Contributing

Issues and PRs welcome at github.com/NgoTaiCo/mcp-codebase-index