# mcp-qdrant-embedding-search

MCP server that searches documents in [Qdrant](https://qdrant.tech/) using embeddings from [LMStudio](https://lmstudio.ai/).

Takes a text query, converts it to a vector via LMStudio's OpenAI-compatible API, and performs semantic search in Qdrant.

## Prerequisites

- **Node.js** 18+
- **LMStudio** running with an embedding model loaded (default: `text-embedding-qwen3-embedding-4b`)
- **Qdrant** running with a collection containing your documents

## Usage

### With npx

```json
{
  "mcpServers": {
    "qdrant-docs": {
      "command": "npx",
      "args": ["-y", "mcp-qdrant-embedding-search"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_COLLECTION": "my_docs",
        "LMSTUDIO_URL": "http://localhost:1234"
      }
    }
  }
}
```

### With node (local)

```bash
git clone https://github.com/plixplox/mcp-qdrant-embedding-search.git
cd mcp-qdrant-embedding-search
npm install
npm run build
```

```json
{
  "mcpServers": {
    "qdrant-docs": {
      "command": "node",
      "args": ["/path/to/mcp-qdrant-embedding-search/dist/index.js"],
      "env": {
        "QDRANT_COLLECTION": "my_docs"
      }
    }
  }
}
```

## Tools

### search_docs

Search documents by semantic similarity.

| Parameter | Type | Required | Description |
|---|---|---|---|
| `query` | string | yes | Search query text |
| `limit` | number | no | Max results (default: 5) |
| `collection` | string | no | Qdrant collection (default: from config) |

### list_collections

List all available Qdrant collections. No parameters.

## Configuration

All settings are configured via environment variables:

| Variable | Default | Description |
|---|---|---|
| `LMSTUDIO_URL` | `http://localhost:1234` | LMStudio server URL |
| `LMSTUDIO_EMBEDDING_MODEL` | `text-embedding-qwen3-embedding-4b` | Embedding model name |
| `QDRANT_URL` | `http://localhost:6333` | Qdrant server URL |
| `QDRANT_API_KEY` | — | Qdrant API key (optional) |
| `QDRANT_COLLECTION` | `documents` | Default collection to search |
| `SEARCH_LIMIT` | `5` | Default number of results |
| `TOOL_SEARCH_NAME` | `search_docs` | Custom name for the search tool |
| `TOOL_SEARCH_DESCRIPTION` | `Search documentation by semantic similarity...` | Custom description for the search tool |
| `TOOL_LIST_NAME` | `list_collections` | Custom name for the list tool |
| `TOOL_LIST_DESCRIPTION` | `List all available Qdrant collections` | Custom description for the list tool |

### Custom tool descriptions

Tool names and descriptions are visible to the LLM and affect when it decides to call them. Customize them to match your use case:

```json
{
  "env": {
    "TOOL_SEARCH_NAME": "search_api_reference",
    "TOOL_SEARCH_DESCRIPTION": "Search the REST API reference. Use when you need endpoint specs, request/response schemas, or auth details."
  }
}
```

## License

ISC