Qdrant RAG MCP Server

How to use

You interact with the MCP server through an MCP client integrated in Claude Code. Start in a project, let the system detect the active project, and then perform semantic search, code understanding, or GitHub-driven workflows. You can switch projects, index code on demand, and run specialized operations such as issue analysis, fix generation, and PR creation while benefiting from progressive context and sub-issue management.

Practical usage patterns you can perform include: deep semantic search across code and configuration files, dependency-aware code exploration, and multi-project knowledge separation. You can enable context tracking to see how Claude’s knowledge grows during a session, monitor token usage, and receive warnings as your context window fills. You can also leverage GitHub integration to analyze issues, generate fixes, create PRs in a safe dry-run mode, and manage projects with V2 tooling.

How to install

Follow these concrete steps to install and run the MCP server for quick, reliable access from Claude Code.

# 1. Clone the MCP server repository
git clone <repository-url> ~/mcp-servers/qdrant-rag
cd ~/mcp-servers/qdrant-rag

# 2. Run the setup script to start Qdrant and install dependencies
./scripts/setup.sh

# 3. Install the MCP server globally for context awareness (one-time)
./install_global.sh

# 4. Test in any project by launching Claude Code and checking the current project context
cd ~/any-project
claude
# In Claude, ask: What's my current project context?

Configuration and operation

To configure the MCP server for local, stdio-based operation, point Claude Code to the Python context- aware entry point with an appropriate working directory. The following configuration shows how to run the MCP server as a local process using Python and the provided script path.

{
  "mcpServers": {
    "qdrant_rag": {
      "type": "stdio",
      "command": "python",
      "args": ["/path/to/qdrant-rag/src/qdrant_mcp_context_aware.py"],
      "env": {
        "MCP_CLIENT_CWD": "${workspaceFolder}"
      }
    }
  }
}

Optional: enabling auto-indexing for smooth operation

Auto-indexing keeps the knowledge index up to date as you modify files. Enable it for the current session or permanently in your shell profile.

# For the current session only
export QDRANT_RAG_AUTO_INDEX=true
claude

# For permanent auto-indexing
echo 'export QDRANT_RAG_AUTO_INDEX=true' >> ~/.bashrc
# or for zsh users:
echo 'export QDRANT_RAG_AUTO_INDEX=true' >> ~/.zshrc

Health checks and troubleshooting

You can run a health check to verify that Qdrant, embeddings, and project context are operating correctly. The health check will report the status of the Qdrant connection, embedding model, disk space, memory usage, and current project context.

If you encounter issues, use the built-in health status and the project-aware logs to isolate problems. Common issues include misdetected projects, MPS-related performance concerns on Apple Silicon, or indexing delays. The system includes retry logic, health monitoring, and clear error messages to guide you.

Notes on usage with GitHub integration

When using the GitHub integration, you can perform intelligent issue analysis, generate fixes, and create PRs with dry-run safety. You can also manage GitHub Projects V2 with smart field assignment and create roadmaps or templates. Sub-issues and hierarchical relationships help you break down complex work into parent/child structures.

Progressive context and embeddings overview

The server uses progressive context management to pull optimal context levels (file → class → method) for token efficiency. It applies specialized, language-aware embeddings for code, config, and documentation, reducing cross-type noise and improving search relevance.

Security and safety

The MCP server includes safety features such as dry-run mode for GitHub actions, rate limiting, audit logging, and file protection to prevent unsafe operations. It also provides health checks and input validation to prevent path traversal and other common issues.

Programmable tooling and examples

You can perform a range of actions via Claude Code, including switching repositories, analyzing issues, generating fixes, and updating GitHub project items. The system supports templates for roadmaps, bug tracking, and feature planning, with project-specific logging and dashboards.

GitHub Issue Resolution

RAG-powered issue analysis, automatic fix generation, and dry-run PR creation with smart safety checks.

GitHub Projects V2 Management

Create and manage GitHub Projects V2, add items, update fields, and track progress with templates.

Context Tracking

Monitor context usage, token consumption, and session history for transparency.

Specialized Embeddings

Code, Config, and Documentation embeddings to improve search relevance.

Progressive Context Management

Multi-level context retrieval with semantic caching and intent detection.

AST-Based Chunking

Structure-aware parsing for code and configuration files to reduce tokens.

Dependency-Aware Search

Include dependent files based on import/export relationships.

Hybrid Search

Combine semantic and keyword search for better precision.

Project-Aware Logging

Isolated, rich logs per project for debugging and analysis.

Health Monitoring

Built-in health checks across all services.