# Qdrant Search MCP

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server for semantic code search via [Qdrant](https://qdrant.tech/) vector database. Designed to work with codebases indexed by [Kilo Code](https://kilocode.ai/) or similar tools.

## Features

- **Semantic code search** - find code by meaning, not just exact strings
- **Multiple embedding providers** - OpenRouter, OpenAI, or local (Ollama)
- **Kilo Code compatible** - works with payload formats from Kilo Code's indexer
- **Collection listing** - browse available Qdrant collections with stats

## Quick Start

### Prerequisites

- Python 3.10+
- A Qdrant instance (cloud or local)
- An embedding API (OpenRouter, OpenAI, or local Ollama)

### Installation

```bash
# Clone the repo
git clone https://github.com/sandeep-wt/qdrant-search-mcp.git
cd qdrant-search-mcp

# Create a virtual environment
python3 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt
```

### Configuration

Set these environment variables:

```bash
# Required
export QDRANT_URL="https://your-qdrant-instance.example.com"
export QDRANT_API_KEY="your-qdrant-api-key"
export COLLECTION_NAME="your-collection-name"

# Embedding provider (default: openrouter)
export EMBEDDING_PROVIDER="openrouter"  # or "openai" or "local"

# For OpenRouter
export OPENROUTER_API_KEY="your-openrouter-key"
export EMBEDDING_MODEL="qwen/qwen3-embedding-8b"

# For OpenAI
# export OPENAI_API_KEY="your-openai-key"
# export EMBEDDING_MODEL="text-embedding-3-small"

# For local (Ollama)
# export EMBEDDING_URL="http://localhost:11434/api/embeddings"
# export EMBEDDING_MODEL="nomic-embed-text"
```

### Running

```bash
python -m qdrant_search_mcp
```

## MCP Client Configuration

### Claude Desktop / Cursor / Kilo Code

Add to your MCP settings:

```json
{
  "mcpServers": {
    "qdrant-search": {
      "command": "python",
      "args": ["-m", "qdrant_search_mcp"],
      "cwd": "/path/to/qdrant-search-mcp",
      "env": {
        "QDRANT_URL": "https://your-qdrant-url",
        "QDRANT_API_KEY": "your-key",
        "COLLECTION_NAME": "your-collection",
        "EMBEDDING_PROVIDER": "openrouter",
        "OPENROUTER_API_KEY": "your-openrouter-key",
        "EMBEDDING_MODEL": "qwen/qwen3-embedding-8b"
      }
    }
  }
}
```

### Hermes Agent

```bash
hermes mcp add qdrant-search \
  --command python \
  --args "-m,qdrant_search_mcp" \
  --cwd /path/to/qdrant-search-mcp \
  --env QDRANT_URL=https://... \
  --env QDRANT_API_KEY=... \
  --env COLLECTION_NAME=... \
  --env OPENROUTER_API_KEY=... \
  --env EMBEDDING_MODEL=qwen/qwen3-embedding-8b
```

## Available Tools

### `semantic_code_search`

Search the codebase index using semantic (meaning-based) search.

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `query` | string | required | Natural language description of what to find |
| `limit` | int | 10 | Maximum number of results |
| `collection` | string | "" | Override Qdrant collection name |

### `list_collections`

List available Qdrant collections with stats (point count, vector dimensions).

## Payload Format Support

The server supports multiple payload formats:

| Field | Kilo Code | Generic |
|-------|-----------|---------|
| File path | `filePath` | `file_path`, `path` |
| Code content | `codeChunk` | `code_chunk`, `content`, `text` |
| Start line | `startLine` | `start_line` |
| End line | `endLine` | `end_line` |

## License

MIT