MCP Qdrant Server

MCP (Model Context Protocol) server for Qdrant Vector Database.

Features

• Collection Management - Create, list, update, and delete collections • Point Operations - CRUD operations for vector points • Search & Discovery - Vector similarity search and scroll/pagination • Payload Management - Set, update, and delete payload data • Full TypeScript - Type-safe implementation with Zod validation

Installation

Global Install

npm install -g @devpuccino/mcp-qdrant

Local Install

npm install @devpuccino/mcp-qdrant

MCP Configuration

Claude Desktop (macOS/Linux)

Add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "qdrant": {
      "command": "npx",
      "args": ["-y", "@devpuccino/mcp-qdrant"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_API_KEY": "your-api-key-optional"
      }
    }
  }
}

Claude Desktop (Windows)

{
  "mcpServers": {
    "qdrant": {
      "command": "npx",
      "args": ["-y", "@devpuccino/mcp-qdrant"],
      "env": {
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | QDRANT_URL | No | http://localhost:6333 | Qdrant server URL | | QDRANT_API_KEY | No | - | API key for authentication |

Selective Tool Loading

The MCP Qdrant Server supports selective tool loading to reduce token usage and improve startup performance.

Command-Line Options

# Load only specific tools
npx @devpuccino/mcp-qdrant --tools=get_collection,search_points

# Load tools by category
npx @devpuccino/mcp-qdrant --categories=collections
npx @devpuccino/mcp-qdrant --categories=points

# Exclude specific tools (e.g., read-only mode)
npx @devpuccino/mcp-qdrant --exclude=delete_collection,delete_points

# List available tools
npx @devpuccino/mcp-qdrant --list-tools

# List available categories
npx @devpuccino/mcp-qdrant --list-categories

# Show help
npx @devpuccino/mcp-qdrant --help

Environment Variables

# Load specific tools
export MCP_TOOLS="get_collection,search_points,count_points"

# Load by categories
export MCP_CATEGORIES="collections"

# Exclude tools
export MCP_EXCLUDE="delete_collection,delete_points,clear_payload"

Available Categories

• collections (7 tools): get_collection, create_collection, delete_collection, update_collection, list_collections, collection_exists, get_optimizations
• points (10 tools): upsert_points, get_point, get_points, delete_points, search_points, scroll_points, count_points, set_payload, delete_payload, clear_payload

Token Savings

| Configuration | Tools | Token Savings | Use Case | |---------------|-------|---------------|----------| | All tools | 17 | 0% | Full access | | Single category | 7-10 | ~40-60% | Focused task | | Exclude destructive | 14-15 | ~10-15% | Read-only mode | | Minimal (2-3 tools) | 2-3 | ~80-85% | Specific task |

MCP Config Examples

Minimal Production Setup:

{
  "mcpServers": {
    "qdrant": {
      "command": "npx",
      "args": ["-y", "@devpuccino/mcp-qdrant"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "MCP_TOOLS": "search_points,get_point,create_collection"
      }
    }
  }
}

Read-Only Access:

{
  "mcpServers": {
    "qdrant": {
      "command": "npx",
      "args": ["-y", "@devpuccino/mcp-qdrant"],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "MCP_EXCLUDE": "delete_collection,delete_points,clear_payload"
      }
    }
  }
}

Authentication

Qdrant supports API Key authentication for securing your vector database.

Getting Your API Key

If your Qdrant instance requires authentication:

1. Qdrant Cloud: Get your API key from the Qdrant Cloud Dashboard
2. Self-Hosted: Set QDRANT__SERVICE__API_KEY environment variable when starting Qdrant

   export QDRANT__SERVICE__API_KEY="your-secret-key"
   qdrant

Using API Key with MCP-Qdrant

Claude Desktop with Authentication:

{
  "mcpServers": {
    "qdrant": {
      "command": "npx",
      "args": ["-y", "@devpuccino/mcp-qdrant"],
      "env": {
        "QDRANT_URL": "https://your-cluster.cloud.qdrant.io:6333",
        "QDRANT_API_KEY": "your-api-key-here"
      }
    }
  }
}

Environment Variables:

export QDRANT_URL="https://your-cluster.cloud.qdrant.io:6333"
export QDRANT_API_KEY="your-api-key-here"
npx @devpuccino/mcp-qdrant

Security Notes:

• ✅ API key is passed via api-key HTTP header
• ✅ Never commit API keys to version control
• ✅ Use environment variables or secret managers
• ✅ Rotate keys periodically

Available Tools

Collection Tools (7 tools)

create_collection

Create a new collection with vector configuration.

{
  "collection_name": "my-collection",
  "vector_size": 384,
  "distance": "Cosine",
  "shard_number": 1,
  "replication_factor": 1,
  "on_disk_payload": true
}

list_collections

List all collections in the Qdrant instance.

{}

get_collection

Get detailed information about a specific collection.

{
  "collection_name": "my-collection"
}

delete_collection

Delete a collection and all its data.

{
  "collection_name": "my-collection"
}

update_collection

Update collection settings (vectors, shards, replication).

{
  "collection_name": "my-collection",
  "vector_size": 768,
  "distance": "Dot"
}

collection_exists

Check if a collection exists.

{
  "collection_name": "my-collection"
}

get_optimizations

Get optimization status of a collection (green = healthy).

{
  "collection_name": "my-collection"
}

Point Tools (10 tools)

upsert_points

Insert or update points in a collection.

{
  "collection_name": "my-collection",
  "points": [
    {
      "id": 1,
      "vector": [0.1, 0.2, 0.3],
      "payload": { "title": "Document 1" }
    }
  ]
}

get_point

Get a single point by ID.

{
  "collection_name": "my-collection",
  "point_id": 1,
  "with_payload": true
}

get_points

Get multiple points by IDs.

{
  "collection_name": "my-collection",
  "point_ids": [1, 2, 3],
  "with_payload": true
}

delete_points

Delete points by IDs or filter.

{
  "collection_name": "my-collection",
  "point_ids": [1, 2],
  "filter": { "must": [{ "key": "category", "match": { "value": "old" } }] }
}

search_points

Search for similar points using vector similarity.

{
  "collection_name": "my-collection",
  "vector": [0.1, 0.2, 0.3],
  "limit": 10,
  "with_payload": true,
  "filter": { "must": [{ "key": "category", "match": { "value": "tech" } }] }
}

scroll_points

Scroll through points with pagination.

{
  "collection_name": "my-collection",
  "limit": 10,
  "offset": 0,
  "with_payload": true,
  "with_vector": false
}

count_points

Count points in a collection (optionally with filter).

{
  "collection_name": "my-collection",
  "filter": { "must": [{ "key": "category", "match": { "value": "tech" } }] },
  "exact": true
}

set_payload

Set or update payload for points.

{
  "collection_name": "my-collection",
  "payload": { "tags": ["AI", "ML"] },
  "point_ids": [1],
  "filter": { "must": [{ "key": "category", "match": { "value": "tech" } }] }
}

delete_payload

Delete specific payload keys from points.

{
  "collection_name": "my-collection",
  "payload_keys": ["old_field"],
  "point_ids": [1]
}

clear_payload

Remove all payload from points.

{
  "collection_name": "my-collection",
  "point_ids": [1, 2]
}

Usage Examples

Create a Collection and Add Points

// Create collection
await create_collection({
  collection_name: "documents",
  vector_size: 768,
  distance: "Cosine"
});

// Add points
await upsert_points({
  collection_name: "documents",
  points: [
    { id: 1, vector: [...], payload: { title: "Doc 1", content: "..." } },
    { id: 2, vector: [...], payload: { title: "Doc 2", content: "..." } }
  ]
});

Search for Similar Documents

const results = await search_points({
  collection_name: "documents",
  vector: queryEmbedding,
  limit: 5,
  with_payload: true,
  filter: {
    must: [{ key: "category", match: { value: "technical" } }]
  }
});

Paginate Through Points

const response = await scroll_points({
  collection_name: "documents",
  limit: 20,
  with_payload: true
});
// response.nextPageOffset for next page

License

MIT License - see LICENSE file for details.