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

Gemini API Key: Get free at Google AI Studio
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:

Connect to your Qdrant Cloud cluster
Create a collection (if needed)
Index your entire codebase
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

MCP Codebase Index