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

• 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

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.

💡 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

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, etc.)

• symbol_name — find exact symbol by name

• language — filter by programming language

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