allfunc/mcp-qdrant repository overview

⁠MCP Qdrant Server

A powerful Model Context Protocol (MCP) server that provides seamless integration with Qdrant vector database. This server enables AI applications to perform advanced vector operations, semantic search, and intelligent document retrieval with automatic embedding generation powered by Ollama.

⁠📋 Table of Contents

• 🚀 Key Features⁠
• 🛠️ Available Tools⁠
• 💾 Installation & Usage⁠
• 🎯 Advanced Payload Filtering⁠
• 🚀 Quick Start Example⁠
• 📚 Resources⁠

⁠🚀 Key Features

⁠Vector Database Operations

• Collection Management: Create, configure, and manage Qdrant collections with customizable vector dimensions and distance metrics
• Smart Point Operations: Insert, update, and delete vector points with rich metadata support
• Batch Processing: Efficient bulk operations for handling large datasets

⁠Intelligent Search Capabilities

• Semantic Similarity Search: Find similar vectors using cosine, euclidean, or dot product distance metrics
• Text-to-Vector Search: Automatic text embedding generation and similarity search in one step
• Advanced Filtering: Powerful payload-based filtering with support for complex boolean logic
• Relevance Scoring: Configurable similarity thresholds for precision control

⁠Performance & Scalability

• Payload Indexing: Create and manage indexes for faster filtering operations
• Pagination Support: Efficient scrolling through large result sets
• Connection Pooling: Optimized connections to Qdrant and Ollama services
• Health Monitoring: Built-in health checks and status monitoring

⁠Developer Experience

• Auto-embedding: Seamless text-to-vector conversion using Ollama models
• Flexible Configuration: Environment-based setup with sensible defaults
• Rich Metadata: Store and query complex JSON payloads alongside vectors
• Error Handling: Comprehensive error reporting and debugging support

⁠🛠️ Available Tools

⁠🔌 Connection & Health

⁠📚 Collection Management

⁠📝 Point Operations

⁠🔍 Search & Discovery

⁠📖 Data Navigation

⁠⚡ Performance & Utilities

⁠🎯 Advanced Payload Filtering

The MCP Qdrant server supports sophisticated payload filtering across search and scroll operations (qdrant_search_similar, qdrant_search_similar_text, qdrant_scroll, and qdrant_scroll_all). This enables precise control over result sets based on metadata conditions.

⁠Filter Types

⁠🔹 Simple Filters

Perfect for basic key-value matching:

{
  "simpleFilter": {
    "category": "technology",
    "status": "published",
    "priority": 1
  }
}

⁠🔹 Complex Filters

For advanced boolean logic and range queries:

Basic Matching

{
  "filter": {
    "must": [
      { "key": "category", "match": { "value": "technology" } }
    ]
  }
}

Multiple Required Conditions

{
  "filter": {
    "must": [
      { "key": "category", "match": { "value": "technology" } },
      { "key": "status", "match": { "value": "active" } },
      { "key": "rating", "range": { "gte": 4.0 } }
    ]
  }
}

Optional Conditions (OR Logic)

{
  "filter": {
    "should": [
      { "key": "author", "match": { "value": "john_doe" } },
      { "key": "author", "match": { "value": "jane_smith" } },
      { "key": "featured", "match": { "value": true } }
    ]
  }
}

Exclusion Logic

{
  "filter": {
    "must": [
      { "key": "category", "match": { "value": "technology" } }
    ],
    "must_not": [
      { "key": "status", "match": { "value": "archived" } },
      { "key": "deprecated", "match": { "value": true } }
    ]
  }
}

Range Filters

{
  "filter": {
    "must": [
      { "key": "score", "range": { "gte": 0.8, "lte": 1.0 } },
      { "key": "created_date", "range": { "gte": "2024-01-01" } },
      { "key": "views", "range": { "gt": 1000 } }
    ]
  }
}

Complex Combined Logic

{
  "filter": {
    "must": [
      { "key": "category", "match": { "value": "technology" } }
    ],
    "should": [
      { 
        "must": [
          { "key": "author", "match": { "value": "expert_author" } },
          { "key": "verified", "match": { "value": true } }
        ]
      },
      { "key": "trending", "match": { "value": true } }
    ],
    "must_not": [
      { "key": "status", "match": { "value": "archived" } }
    ]
  }
}

⁠💾 Installation & Usage

⁠Option 1: Using Docker (Recommended)

The easiest way to use this MCP server is through Docker:

# Add the MCP server to VS Code as Stdio mode
code --add-mcp '{"name":"mcp-qdrant","command":"docker","args":["run", "-i", "--rm", "--env-file", "'${HOME}'/.mcp-credentials", "--name", "mcp-qdrant", "--network", "host", "allfunc/mcp-qdrant", "stdio"]}'

# Add the MCP server to VS Code as httpStream mode
code --add-mcp '{"name":"mcp-qdrant","command":"docker","args":["run", "-i", "--rm", "--env-file", "'${HOME}'/.mcp-credentials", "--name", "mcp-qdrant", "--network", "host", "allfunc/mcp-qdrant"]}'

# Add the MCP server to Claude as a transport
# claude mcp add --transport http <name> <url>

claude mcp add -s user --transport http mcp-qdrant http://localhost/mcp

⁠Option 2: Local Development

# Clone and install
git clone https://github.com/allfunc/mcp-qdrant.git
cd mcp-qdrant/app
bun install

# Run the server
bun run src/index.ts

⁠Option 3: Using Docker Run

  docker run --rm -it \
    -p 65534:65534 \
    -p 65533:65533 \
    --env-file $HOME/.mcp-credentials \
    --network host \
    allfunc/mcp-qdrant 

⁠Environment Configuration

Create a .mcp-credentials file in your home directory with the following environment variables:

# Qdrant Configuration
QDRANT_URL=http://localhost:6333
QDRANT_API_KEY=your_api_key_here  # Optional

# Ollama Configuration for Embeddings
OLLAMA_URL=http://localhost:11434
OLLAMA_MODEL=mxbai-embed-large

⁠Configuration Options

⁠🚀 Quick Start Example

1. Connect to Qdrant:

   // The server will automatically connect using your environment configuration
   

   Copy

2. Create a collection:

   qdrant_create_collection({
     name: "my_documents",
     vectorSize: 1024,
     distance: "Cosine"
   })
   

   Copy

3. Insert text with automatic embedding:

   qdrant_insert_text({
     collectionName: "my_documents",
     text: "This is a sample document about machine learning",
     payload: {
       category: "technology",
       author: "john_doe",
       timestamp: "2024-01-01"
     }
   })
   

   Copy

4. Search for similar content:

   qdrant_search_similar_text({
     collectionName: "my_documents",
     queryText: "artificial intelligence",
     limit: 5,
     simpleFilter: {
       category: "technology"
     }
   })
   

   Copy

⁠📚 Resources

• GitHub Repository: https://github.com/allfunc/mcp-qdrant⁠
• Docker Hub: https://hub.docker.com/r/allfunc/mcp-qdrant⁠
• Qdrant Documentation: https://qdrant.tech/documentation/⁠
• Model Context Protocol: https://modelcontextprotocol.io/⁠