workspace-qdrant-mcp

Purpose

workspace-qdrant-mcp is a project-scoped vector database designed specifically for AI coding assistants, providing project-wide memory capabilities for coding assistants. Built on Qdrant, it can index project code and documentation into Qdrant and provides hybrid semantic and keyword search, while supporting automatic project detection.

Key Capabilities

• Hybrid Search: Combines semantic similarity with keyword matching, using Reciprocal Rank Fusion to merge results.
• Project Detection: Automatically detects Git repositories and creates project-scoped collections.
• 7 MCP Tools: search, retrieve, rules, store, grep, list, embedding.
• Code Intelligence: Uses tree-sitter for semantic chunking, and integrates LSP (Language Server Protocol) to support active projects.
• Code Graph: Provides a relationship graph, including algorithms such as PageRank, community detection, and betweenness centrality.
• High-Performance CLI: The Rust-based wqm command-line tool.
• Background Daemon: memexd for continuous file monitoring and processing.
• Dedicated Collections: Provides dedicated collections for the knowledge base, LLM behavior rules, and LLM scratchpad.
• Observability: The daemon exposes metrics and traces, supporting Prometheus (/metrics, pull mode) and OTLP tracing (push mode), both disabled by default.

Usage

Dependency Requirements

• Qdrant:docker run -d -p 6333:6333 -v qdrant_storage:/qdrant/storage qdrant/qdrant
• C Compiler: Required to compile tree-sitter grammars on first use. tree-sitter grammars are distributed as C source code and compiled locally.
  • macOS:xcode-select --install（Xcode Command Line Tools）
  • Linux：apt install build-essential(Debian/Ubuntu) or dnf groupinstall "Development Tools"(Fedora)
  • Windows: Install Visual Studio Build Tools with the C++ workload
• Clang/LLVM: Only required when building memexd from source, for the LadybugDB C++ core (the default graph backend). Prebuilt binaries (Homebrew, release artifacts) do not require it.
  • macOS: Xcode Command Line Tools include Clang (xcode-select --install）
  • Linux：apt install clang libclang-dev(Debian/Ubuntu) or dnf install clang(Fedora)
  • Alternative: Build with the SQLite-only backend, which requires no C++ toolchain — cargo build --no-default-features --features sqlite

Installation Options

• Option 1: Homebrew (Recommended — macOS and Linux)
• Option 2: Prebuilt Binaries: Install wqm, memexd, and workspace-qdrant-mcp to ~/.local/bin(Linux/macOS) or %LOCALAPPDATA%\wqm\bin(Windows).
• Option 3: Build from Source

For detailed instructions and platform-specific considerations, see the Installation Reference. Windows users, see the Windows Installation Guide.

Integration Configuration

• Claude Desktop: Configure in claude_desktop_config.json .
• CLAUDE.md Integration: Add the relevant configuration to the project's CLAUDE.md (or the global ~/.claude/CLAUDE.md) so that Claude Code proactively uses workspace-qdrant.
• Claude Code Integration:wqm init hooks reads and writes Claude Code's settings.json, whose location is resolved according to rules.

Observability Configuration

• Prometheus: After being enabled via configuration or environment variables, scrape /metrics。--metrics-port <N> CLI flag is a shortcut that forces enabled=true and overrides the port. For examples, see docs/observability/prometheus-scrape-example.yaml, and for the Grafana 10 dashboard, see docs/observability/memexd-telemetry-dashboard.json.
• OTLP Tracing: When conditions are met, #[tracing::instrument] spans on the queue processor, watcher, gRPC, embedding, and Qdrant paths are exported via OTLP/gRPC. Standard OpenTelemetry environment variables are supported:OTEL_SERVICE_NAME、OTEL_EXPORTER_OTLP_ENDPOINT、OTEL_EXPORTER_OTLP_PROTOCOL、OTEL_EXPORTER_OTLP_HEADERS、OTEL_TRACES_SAMPLER_ARG.
• Note: OTLP metrics export is not yet implemented — Prometheus is the canonical metrics interface.

Architecture Notes

The Rust daemon handles file monitoring, embedding generation, code graph extraction, and queue processing. All writes are routed through the daemon to ensure consistency.

Use Cases

• Provide project-wide code and documentation memory for AI coding assistants (such as Claude Code).
• Need hybrid semantic and keyword search within a project codebase.
• Need code intelligence analysis (tree-sitter chunking, LSP integration) and code graph analysis (PageRank, community detection, etc.).
• Need to maintain dedicated collections for knowledge bases, LLM behavior rules, and scratchpads.

Limitations and Status

• The project is currently in the v0.2.0 rebuild phase, being rebuilt from scratch, with goals including a unified storage model, better search quality, more reliable file watching, and a clearer architecture, while providing existing users with a migration that requires no reindexing. The design lock target is early July, after which external contributions will be opened.
• OTLP metrics export is not yet implemented.
• Building memexd from source requires Clang/LLVM (unless using the SQLite-only backend).
• First use requires a C compiler to compile tree-sitter grammars.

Documentation and License

• Provides documentation including Quick Start (get started in 5 minutes), User Manual, LLM Integration, Installation, Windows installation guide, CLI Reference, MCP Tools, Configuration, Architecture, and more.
• Licensed under the Apache License 2.0.
• Inspired by claude-qdrant-mcp.