qmcp - QDrant MCP Server for OpenCode

Semantic search server for code and documentation using Qdrant vector database.

Language: English | Русский

Features

• Semantic Search: Find code and documentation using natural language queries

• Multi-language Support: Python, Go, JavaScript, TypeScript, Java, C#, Markdown

• Markdown Section Chunking: Markdown files are split into per-section chunks (##/### headers) with precise line ranges - search points at the exact section instead of the whole file, and file tails beyond 10 KB are indexed too

• Compact Search Responses: Search returns pointer fields only (file_path, line_start, line_end, type, name) - enough for a targeted read, without bloating the context

• Live Updates: File watcher for automatic reindexing

• Incremental Indexing: Only index changed files

• Gitignore Support: Respects .gitignore - excludes node_modules, __pycache__, .venv, build artifacts, etc.

• Cleanup: Remove stale vectors for deleted/changed files

• Diagnostics: Introspection tools to understand what's indexed

• OpenCode Skill: Natural language interface for Qdrant management

Related MCP server: Tea Rags MCP

Installation

Via PyPI (Recommended)

pip install qmcp-qdrant

Via uv

uv tool install qmcp-qdrant

From Source

git clone https://github.com/BigKAA/qmcp.git
cd qmcp
make install

Updating

Via uv (Recommended)

uv tool upgrade qmcp-qdrant

Via pip

pip install --upgrade qmcp-qdrant

Quick Start

1. Ensure Qdrant is running

For Kubernetes deployment, see Qdrant on Kubernetes.

2. Add MCP Server to OpenCode

opencode mcp add qmcp-qdrant qmcp-qdrant

⚠️ Note: Environment variables must be set in ~/.config/opencode/opencode.json config file.

Configuration

💡 Model Cache: Set EMBEDDING_CACHE_DIR to persist models across restarts. First launch downloads the model (~13MB), subsequent launches use cached version.

💡 Multiple clients, one machine: every MCP client spawns its own qmcp process, and each holds its own embedding model. qmcp deduplicates indexing across processes with file locks (INDEX_LOCK_DIR) and caps ONNX threads (EMBEDDING_THREADS, default 4) so N processes cannot saturate every core. Keep WATCH_PATHS scoped to trees you actively work in - a monorepo-scale path makes every process walk it on each poll.

💡 WATCH_PATHS examples:

• Single path: WATCH_PATHS=/home/user/project

• Multiple paths: WATCH_PATHS=/home/user/project,/home/user/docs

• JSON array: WATCH_PATHS=["/home/user/project", "/home/user/docs"]

3. That's It!

OpenCode will automatically discover and use the semantic search tools.

Manual Configuration (Alternative)

If opencode mcp add doesn't work, edit ~/.config/opencode/opencode.json directly:

{
  "mcp": {
    "qmcp-qdrant": {
      "type": "local",
      "command": ["qmcp-qdrant"],
      "environment": {
        "QDRANT_URL": "http://192.168.218.190:6333",
        "WATCH_PATHS": "/home/user/shared-docs,/home/user/shared-snippets"
      }
    }
  }
}

For Python module:

{
  "mcp": {
    "qmcp-qdrant": {
      "type": "local",
      "command": ["python", "-m", "qmcp.server"],
      "environment": {
        "QDRANT_URL": "http://192.168.218.190:6333",
        "WATCH_PATHS": "/home/user/shared-docs,/home/user/shared-snippets"
      }
    }
  }
}

Indexing Notes

⚠️ Important: Full indexing and reindexing of large projects can take a significant amount of time (minutes to hours depending on project size).

For large codebases, prefer:

• Incremental reindex (mode="incremental") - only updates changed files based on content hashes

• File watcher - enables automatic live updates when files change

Markdown Chunking

Markdown files are chunked per section (headers ## and ### by default). Oversized sections (> 8 KB) are additionally split by paragraph boundaries, never inside code fences. Each chunk carries precise line_start/line_end, so qdrant_search results point to the exact section for a targeted read.

Files without headers fall back to a single document chunk (paragraph-split when oversized).

⚠️ BREAKING (existing collections): The chunk schema changed (per-section chunks instead of one chunk per markdown file). Existing markdown collections must be fully reindexed after upgrading:

qdrant_reindex(path="/path/to/project", collection="docs", mode="full")

Incremental reindex will not migrate unchanged files - they keep the old single-chunk layout until a full reindex runs.

Score Threshold Note

The default score_threshold=0.7 is calibrated for bge-* embedding models. For paraphrase-multilingual-* models the top score is typically ~0.64, so the default threshold filters out everything - lower the threshold explicitly for those models.

Automatic Indexing Strategy

qmcp supports automatic indexing on two levels:

1. Server startup level — on MCP startup, the server automatically tries to start a watcher for WATCH_PATHS.

2. Workspace session level — because one global MCP server can be shared across multiple repositories, agents should check the watcher state for the current workspace and call qdrant_watch_ensure(paths=[workspace_root]) when the workspace path is missing.

Recommended OpenCode flow for every new workspace:

status = qdrant_get_status()

# If watcher is not active or the current repo is not covered,
# safely extend the watcher without dropping other projects.
qdrant_watch_ensure(paths=["/absolute/path/to/current/workspace"])

qdrant_watch_ensure merges the current workspace with already watched paths and WATCH_PATHS, making it safe for a single global MCP shared by multiple projects.

MCP Tools

Search & Indexing

💡 Tip: Use qdrant_search with filters for precise results:

• chunk_type — filter by code type (function_def, class_def, section, document)

• symbol_name — find exact symbol by name (for markdown: section header text)

• language — filter by programming language

Results are compact pointers (score, file_path, type, name, line_start, line_end) - use them for a targeted file read instead of loading whole files.

See docs/STRUCTURED_METADATA.md for detailed examples.

Collection Management

Diagnostics & Introspection

Maintenance

Diagnostic Tools Usage Examples

# Diagnose a collection - see what's indexed, file types, issues
qdrant_diagnose_collection(collection="myproject")

# List indexed files with pagination
qdrant_list_indexed_files(collection="myproject", limit=50, offset=0)

# Filter by file type
qdrant_list_indexed_files(collection="myproject", file_type=".py")

# Compare Qdrant state with filesystem
qdrant_diff_collection(collection="myproject", repo_path="/path/to/repo")

OpenCode Skill

The project includes an OpenCode skill for natural language management of Qdrant.

Installation

# Copy skill to OpenCode skills directory
cp -r skills/qmcp-manager ~/.config/opencode/skills/

Usage

Once installed, OpenCode will automatically activate the skill when you ask questions like:

Workflows Provided by Skill

1. Quick Status - Check collection state with qdrant_list_collections

2. Full Diagnostics - Detailed analysis with qdrant_diagnose_collection

3. Diff - Compare Qdrant with filesystem using qdrant_diff_collection

4. Safe Cleanup - Preview with dry-run, then confirm deletion

5. Smart Reindex - Incremental updates based on file hashes

Skill Location

skills/qmcp-manager/SKILL.md

Manage MCP Servers

opencode mcp list          # List all MCP servers
opencode mcp debug qmcp-qdrant     # Debug connection issues
opencode mcp logout qmcp-qdrant    # Remove MCP server

Development

make install      # Install dependencies
make test         # Run tests
make lint         # Lint code
make format       # Format code
make mcp-dev      # Run with MCP inspector

Troubleshooting

If you encounter issues, see the Troubleshooting Guide for:

• Embedding Model Issues — indexed_vectors_count: 0 diagnosis and fix

• Connection Problems — Qdrant connection troubleshooting

• Search Returns No Results — Empty search results debugging

License

Apache 2.0