workspace-qdrant-mcp 0.3.0

Project-scoped Qdrant MCP server with scratchbook functionality

THIS PROJECT IS IN ACTIVE DEVELOPMENT AND IS NOT YET READY FOR PRODUCTION, BUT SOON!

workspace-qdrant-mcp

Project-scoped Qdrant MCP server with hybrid search and configurable collections

---

Inspired by claude-qdrant-mcp with enhanced project detection, Python implementation, and flexible collection management.

workspace-qdrant-mcp provides intelligent vector database operations through the Model Context Protocol (MCP), featuring automatic project detection, hybrid search capabilities, and configurable collection management for seamless integration with Claude Desktop and Claude Code.

✨ Key Features

• 🏗️ Auto Project Detection - Smart workspace-scoped collections with Git repository awareness
• 🔍 Hybrid Search - Combines semantic and keyword search with reciprocal rank fusion
• 📝 Scratchbook Collections - Personal development journals for each project
• 🎯 Subproject Support - Git submodules with user-filtered collection creation
• ⚙️ Interactive Setup - Guided configuration wizard with health checks
• 🚀 High Performance - Rust-powered components with evidence-based benchmarks
• 🌐 Cross-Platform - Native support for macOS (Intel/ARM), Linux (x86_64/ARM64), Windows (x86_64/ARM64)
• 🛡️ Enterprise Ready - Comprehensive security scanning and quality assurance

🔧 MCP Tools

workspace-qdrant-mcp provides 4 comprehensive MCP tools for vector database operations:

1. store - Content Storage

Store any type of content in the vector database with automatic embedding generation and metadata enrichment.

• Supports text, code, documentation, notes, and more
• Automatic project detection and collection routing
• Metadata enrichment (file_type, branch, project_id)
• Background processing via Rust daemon for optimal performance

2. search - Hybrid Search

Search across collections with powerful hybrid semantic + keyword matching.

• hybrid mode: Combines semantic similarity with keyword matching (default)
• semantic mode: Pure vector similarity search for conceptual matches
• exact mode: Keyword and symbol exact matching
• Automatic result optimization using Reciprocal Rank Fusion (RRF)
• Branch filtering (search current branch or all branches)
• File type filtering (code, docs, tests, etc.)

3. manage - Collection Management

Manage collections, system status, and configuration.

• List all collections with statistics
• Create and delete collections
• Get workspace status and health information
• Initialize project collections
• Cleanup empty collections and optimize storage

4. retrieve - Direct Document Access

Retrieve documents by ID or metadata without search ranking.

• Direct document ID lookup
• Metadata-based filtering
• Branch and file type filtering
• Efficient bulk retrieval

All tools seamlessly integrate with Claude Desktop and Claude Code for natural language interaction.

Table of Contents

• ✨ Key Features
• 🔧 MCP Tools
• Quick Start
  • Daemon Service Installation
  • Interactive Setup
• Prerequisites
• Installation
• Daemon Service Setup
• MCP Integration
• Configuration
• Usage
• CLI Tools
• Documentation
• Troubleshooting
• Contributing
• License

Quick Start

Daemon Service Installation

For production deployments with continuous document processing:

1. Install the package: uv tool install workspace-qdrant-mcp
2. Install daemon service: wqm service install
3. Start the service: wqm service start
4. Verify installation: wqm service status

The daemon service provides:

• ✅ Continuous document monitoring and processing
• ✅ Background embedding generation with file watching
• ✅ Automatic startup on system boot with crash recovery
• ✅ Robust error recovery and structured logging
• ✅ IPC communication for Python integration

📖 Complete Installation Guide: docs/daemon-installation.md

Interactive Setup

For quick testing and development:

1. Install the package: uv tool install workspace-qdrant-mcp
2. Run the setup wizard: workspace-qdrant-setup
3. Start using with Claude: The wizard configures everything automatically

Or use YAML configuration for project-specific setups:

workspace-qdrant-mcp --config=my-project.yaml

Prerequisites

Qdrant server must be running - workspace-qdrant-mcp connects to Qdrant for vector operations.

• Local: Default http://localhost:6333
• Cloud: Requires QDRANT_API_KEY environment variable

For local installation, see the Qdrant repository. For documentation examples, we assume the default local setup.

Installation

# Install globally with uv (recommended)
uv tool install workspace-qdrant-mcp

# Or with pip
pip install workspace-qdrant-mcp

After installation, run the setup wizard:

workspace-qdrant-setup

This interactive wizard will guide you through configuration, test your setup, and get you ready to use the MCP server with Claude in minutes.

For development setup, see CONTRIBUTING.md.

Daemon Service Setup

The memexd daemon provides continuous document processing and monitoring capabilities for production deployments:

Quick Service Installation

# Install daemon service (auto-detects platform)
wqm service install

# Start the service
wqm service start

# Verify installation
wqm service status

Service Management

# Service control
wqm service start|stop|restart|status

# View logs
wqm service logs

# Health monitoring
workspace-qdrant-health --daemon

Daemon Benefits

The daemon service automatically:

• 📁 Monitors document changes in real-time with file watching
• 🤖 Generates embeddings in the background for optimal performance
• 🔄 Maintains collection health and consistency across restarts
• 🔌 Provides IPC communication for seamless Python integration
• 🚀 Starts on system boot with automatic crash recovery

📖 Complete Installation Guide: docs/daemon-installation.md - Covers systemd (Linux), launchd (macOS), and Windows Service with security configurations.

MCP Integration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "workspace-qdrant-mcp": {
      "command": "workspace-qdrant-mcp",
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "COLLECTIONS": "project",
        "GLOBAL_COLLECTIONS": "docs,references"
      }
    }
  }
}

Claude Code

claude mcp add workspace-qdrant-mcp

Configure environment variables through Claude Code's settings or your shell environment.

Configuration

Environment Variables

Variable	Default	Description
QDRANT_URL	http://localhost:6333	Qdrant server URL
QDRANT_API_KEY	(none)	Required for Qdrant cloud, optional for local
COLLECTIONS	project	Collection suffixes (comma-separated)
GLOBAL_COLLECTIONS	(none)	Global collection names (comma-separated)
GITHUB_USER	(none)	Filter projects by GitHub username
FASTEMBED_MODEL	sentence-transformers/all-MiniLM-L6-v2	Embedding model (see options below)

YAML Configuration

For easier project-specific configuration management, you can use YAML configuration files:

# Start with YAML configuration
workspace-qdrant-mcp --config=project-config.yaml

Configuration Precedence:

1. Command line arguments (highest)
2. YAML configuration file
3. Environment variables
4. Default values (lowest)

Example YAML configuration:

# project-config.yaml
host: "127.0.0.1"
port: 8000
debug: false

qdrant:
  url: "http://localhost:6333"
  api_key: null
  timeout: 30
  prefer_grpc: false

embedding:
  model: "sentence-transformers/all-MiniLM-L6-v2"
  enable_sparse_vectors: true
  chunk_size: 800
  chunk_overlap: 120
  batch_size: 50

workspace:
  collection_types: ["project"]
  global_collections: ["docs", "references", "standards"]
  github_user: null
  auto_create_collections: false
  memory_collection_name: "__memory"
  code_collection_name: "__code"

Benefits:

• Project-specific: Each project can have its own config
• Version control: YAML configs can be committed to your repo
• Team sharing: Easy to share configurations
• Validation: Built-in validation with helpful error messages
• Documentation: Self-documenting with structure and comments

See YAML_CONFIG.md for complete documentation and examples.

Embedding Model Options

Choose the embedding model that best fits your system resources and quality requirements:

Lightweight (384D) - Good for limited resources:

• sentence-transformers/all-MiniLM-L6-v2 (default) - Fast, low memory

Balanced (768D) - Better quality, moderate resources:

• BAAI/bge-base-en-v1.5 - Excellent for most use cases
• jinaai/jina-embeddings-v2-base-en - Good multilingual support
• thenlper/gte-base - Google's T5-based model

High Quality (1024D) - Best results, high resource usage:

• BAAI/bge-large-en-v1.5 - Top performance for English
• mixedbread-ai/mxbai-embed-large-v1 - Latest state-of-the-art

Configuration example:

# Use a more powerful model
export FASTEMBED_MODEL="BAAI/bge-base-en-v1.5"

# Or in Claude Desktop config
"env": {
  "FASTEMBED_MODEL": "BAAI/bge-base-en-v1.5"
}

Collection Naming

Collections are automatically created based on your project and configuration:

Always Created:

• {project-name}-scratchbook → Auto-created for notes, ideas, todos, and code snippets

Project Collections:

• COLLECTIONS="project" → creates {project-name}-project
• COLLECTIONS="docs,tests" → creates {project-name}-docs, {project-name}-tests

Global Collections (User Choice):

• GLOBAL_COLLECTIONS="docs,references" → creates docs, references (shared across projects)

Example: For project "my-app" with COLLECTIONS="docs,tests":

• my-app-scratchbook (automatically created for notes)
• my-app-docs (project documentation)
• my-app-tests (test-related documents)
• docs (global documentation)
• references (global references)

Scratchbook Collections

Every project automatically gets a {project-name}-scratchbook collection for capturing development thoughts and notes. This is your personal development journal for the project.

What goes in scratchbook collections:

• 📝 Meeting notes and action items
• 💡 Ideas and implementation thoughts
• ✅ TODOs and reminders
• 🔧 Code snippets and implementation patterns
• 🏗️ Architecture decisions and rationale
• 🐛 Bug reports and troubleshooting notes
• 📊 Research findings and links
• 🎯 Project goals and milestones

Example scratchbook entries:

"Discussed API rate limiting in team meeting - need to implement exponential backoff"
"Found solution for memory leak in worker threads - use weak references"
"TODO: Update deployment docs after container changes"
"Code snippet: async context manager pattern for database connections"

Subproject Support (Git Submodules)

For repositories with Git submodules, additional collections are created automatically:

Requirements:

• Must set WORKSPACE_QDRANT_WORKSPACE__GITHUB_USER=yourusername
• Only submodules owned by you get collections (prevents vendor/third-party sprawl)
• Without github_user configured, only main project collections are created (conservative approach)

Example with subprojects:

# Repository: my-monorepo with submodules
# - frontend/ (github.com/myuser/frontend)
# - backend/ (github.com/myuser/backend)
# - vendor-lib/ (github.com/vendor/lib) ← ignored

# Collections created:
my-monorepo-scratchbook    # Main project notes
my-monorepo-project        # Main project docs
frontend-scratchbook       # Frontend notes
frontend-project          # Frontend docs
backend-scratchbook       # Backend notes
backend-project           # Backend docs
# No collections for vendor-lib (different owner)

Cross-Collection Search

Important: All MCP search commands search across ALL your collections simultaneously.

When you use Claude with commands like:

• "Search my project for authentication code"
• "Find all references to the payment API"
• "What documentation do I have about deployment?"

The search automatically includes:

• ✅ Main project collections (project-name-*)
• ✅ All subproject collections (subproject-*)
• ✅ Global collections (docs, references, etc.)
• ✅ All scratchbook collections (your notes and ideas)

This gives you unified search across your entire workspace - you don't need to specify which collection to search.

Usage

Interact with your collections through natural language commands in Claude:

Store Information:

• "Store this note in my project scratchbook: [your content]"
• "Add this document to my docs collection: [document content]"

Search & Retrieve:

• "Search my project for information about authentication"
• "Find all references to the API endpoint in my scratchbook"
• "What documentation do I have about deployment?"

Hybrid Search:

• Combines semantic search (meaning-based) with keyword search (exact matches)
• Automatically optimizes results using reciprocal rank fusion (RRF)
• Searches across project and global collections

CLI Tools

Interactive Setup Wizard

Get up and running in minutes with the guided setup wizard:

# Interactive setup with guided prompts
workspace-qdrant-setup

# Advanced mode with all configuration options
workspace-qdrant-setup --advanced

# Non-interactive mode for automation
workspace-qdrant-setup --non-interactive

The setup wizard:

• Tests Qdrant connectivity and validates configuration
• Helps choose optimal embedding models
• Configures Claude Desktop integration automatically
• Creates sample documents for immediate testing
• Provides final system verification

Diagnostics and Testing

Comprehensive troubleshooting and health monitoring:

# Full system diagnostics
workspace-qdrant-test

# Test specific components
workspace-qdrant-test --component qdrant
workspace-qdrant-test --component embedding

# Include performance benchmarks
workspace-qdrant-test --benchmark

# Generate detailed report
workspace-qdrant-test --report diagnostic_report.json

Health Monitoring

Real-time system health and performance monitoring:

# One-time health check
workspace-qdrant-health

# Continuous monitoring with live dashboard
workspace-qdrant-health --watch

# Detailed analysis with optimization recommendations
workspace-qdrant-health --analyze

# Generate health report
workspace-qdrant-health --report health_report.json

Collection Management

Use wqutil for collection management and administration:

# List collections
wqutil list-collections

# Collection information
wqutil collection-info my-project-scratchbook

# Validate configuration
workspace-qdrant-validate

# Check workspace status
wqutil workspace-status

Document Ingestion

Batch process documents for immediate searchability:

# Ingest documents from a directory
workspace-qdrant-ingest /path/to/docs --collection my-project

# Process specific formats only
workspace-qdrant-ingest /path/to/docs -c my-project -f pdf,md

# Preview what would be processed (dry run)
workspace-qdrant-ingest /path/to/docs -c my-project --dry-run

Documentation

• Architecture - System architecture diagrams and component interactions
• CLI Reference - Complete command-line reference for all wqm commands
• Daemon Service Installation - Complete system service setup guide for Linux (systemd), macOS (launchd), and Windows Service
• API Reference - Complete MCP tools documentation
• Contributing Guide - Development setup and guidelines
• Release Process - Automated releases and emergency procedures
• Trusted Publishing Setup - PyPI security configuration
• Benchmarking - Performance testing and metrics

Troubleshooting

Quick Diagnostics:

# Run comprehensive system diagnostics
workspace-qdrant-test

# Get real-time health status
workspace-qdrant-health

# Run setup wizard to reconfigure
workspace-qdrant-setup

Connection Issues:

# Test Qdrant connectivity specifically
workspace-qdrant-test --component qdrant

# Verify Qdrant is running
curl http://localhost:6333/collections

# Validate complete configuration
workspace-qdrant-validate

Performance Issues:

# Run performance benchmarks
workspace-qdrant-test --benchmark

# Monitor system resources
workspace-qdrant-health --watch

# Get optimization recommendations
workspace-qdrant-health --analyze

Collection Issues:

# List current collections
wqutil list-collections

# Check project detection
wqutil workspace-status

For detailed troubleshooting, see API.md.

🚀 Release Process

This project uses fully automated semantic versioning and PyPI publishing. Every commit to the main branch is analyzed for release necessity using conventional commits.

Automated Release Pipeline

• Semantic Analysis: Commits analyzed for version impact (major/minor/patch)
• Cross-Platform Builds: Automatic wheel building for Linux, macOS, Windows
• Comprehensive Testing: TestPyPI validation before production release
• Security Scanning: Dependency and vulnerability analysis
• Release Verification: Multi-platform installation testing
• Emergency Rollback: Automated rollback capabilities for critical issues

Commit Message Format

# Feature releases (minor version bump: 1.0.0 → 1.1.0)
git commit -m "feat: add new hybrid search algorithm"

# Bug fixes (patch version bump: 1.0.0 → 1.0.1)
git commit -m "fix: resolve memory leak in document processing"

# Breaking changes (major version bump: 1.0.0 → 2.0.0)
git commit -m "feat!: redesign MCP tool interface

BREAKING CHANGE: Tool parameters have changed."

# No release (documentation, tests, chores)
git commit -m "docs: update API examples"
git commit -m "test: add integration tests"
git commit -m "chore: update dependencies"

📚 Documentation: See docs/RELEASE_PROCESS.md for complete release documentation and emergency procedures.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines on:

• Setting up the development environment
• Running tests and benchmarks
• Code style and quality requirements
• Submitting pull requests

💬 Community

Join our community discussions for support, ideas, and collaboration:

• GitHub Discussions - Community Q&A, feature ideas, and showcases
• Community Guidelines - How we work together
• Discussion Guide - Getting the most from community discussions

For bug reports and specific feature requests, please open an issue on GitHub.

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

Related Projects:

• claude-qdrant-mcp - Original TypeScript implementation
• Qdrant - Vector database
• FastMCP - MCP server framework