MCP服务器

🚀 Installation & Compilation

Direct One-Line Installation

If you simply want to install the pre-compiled binary on your client machine (supports Linux, macOS, and Windows/WSL), you can run the following command directly:

curl -fsSL https://raw.githubusercontent.com/weverkley/qdrant-mcp-server/main/install.sh | sh

To install a specific version, pass the VERSION environment variable:

curl -fsSL https://raw.githubusercontent.com/weverkley/qdrant-mcp-server/main/install.sh | VERSION=v1.0.0 sh

[!TIP] Automated PATH Setup: If the installer does not have write permissions to /usr/local/bin, it will fallback to installing in ~/.local/bin and automatically append the path export to your shell configuration profile (~/.bashrc, ~/.zshrc, ~/.profile, or ~/.bash_profile) so the CLI is immediately available after terminal restart.

---

Build with debug symbols stripped for maximum execution speed and minimal size

go build -ldflags="-s -w" -o ~/bin/qdrant-mcp-server main.go

Alternatively, you can build directly to your working directory:

---

🎓 Installing Agent Skills

To help your AI agent (like Cursor, Windsurf, Cline, or Copilot) understand when and how to use the semantic search capabilities, you can install specialized skills (rules files) directly into your workspace.

Run the compiled server binary with the list-skills and install-skill subcommands:

2. Install a Skill for an Agent

Install the rules directly in your active project's root folder: ```bash

Install Cursor rules (.cursorrules)

./qdrant-mcp-server install-skill cursor

Install Cline rules (.clinerules)

./qdrant-mcp-server install-skill cline

Install Copilot instructions (.github/copilot-instructions.md)

./qdrant-mcp-server install-skill copilot

Install Codex instructions (.codex/mcp-instructions.md)

./qdrant-mcp-server install-skill codex

Install ALL supported agent skills at once

./qdrant-mcp-server install-skill all

You can also specify a custom target path as the last parameter:

---

📚 Codex / Knowledge Base Setup

Many developers maintain local documentation, architecture guidelines, team handbooks, or a personal knowledge base inside their repository or workspace using folders like .codex or .obsidian.

By default, the server ignores all hidden directories (those starting with a .) to prevent performance bottlenecks. You can explicitly instruct the server to monitor, index, and query your Codex notes by adding .codex or .obsidian to the INCLUDE_HIDDEN_DIRS environment variable.

Setup Example

Simply append your documentation directory to the INCLUDE_HIDDEN_DIRS variable in your MCP configuration:

"env": {
  "WATCH_DIRECTORY": "/home/user/Workspace/my-project",
  "INCLUDE_HIDDEN_DIRS": ".codex,.obsidian",
  "QDRANT_COLLECTION": "my-project-vectors",
  "OLLAMA_HOST": "http://127.0.0.1:11434",
  "EMBEDDING_MODEL": "nomic-embed-text"
}

⚙️ Environment Variables

The server relies on the following environment variables for its configuration:

---

⏱️ Auto-Discovery & Zero-Config CLI

When running CLI subcommands (like ingest), the server automatically looks up your existing agent environment variables by searching upwards from the current working directory for configuration files: - .mcp.json / mcp.json - .claude/settings.local.json - .codex/config.toml / config.toml

It also checks your user-level Claude settings file: - ~/.claude/settings.json

If it finds one of these configurations, it automatically parses it and loads the configured environment variables (like QDRANT_COLLECTION, WATCH_DIRECTORY, OLLAMA_HOST, and EMBEDDING_MODEL) into the active session. This means you can run manual ingestions inside your project folder with zero manual configuration!

```bash

🤖 Smart CLI & Manual Ingestion

The qdrant-mcp-server binary itself is a highly functional command-line tool. While it is designed to run automatically as a background process via your AI editor, you can also run manual operations—like bulk codebase ingestion—directly from your shell.

This is especially helpful when indexing extremely large codebases for the first time, as doing it in the background can sometimes feel slow or resource-intensive.

🎛️ Explicit CLI Overrides & Standalone Mode

If you want to run the tool standalone, or override specific variables on the fly, you can pass command-line arguments (parameters):

```bash

📋 Supported CLI Flags:

• --collection, -c <name>: Qdrant collection name (QDRANT_COLLECTION)
• --watch-dir, -w <path>: Directory to watch/index (WATCH_DIRECTORY)
• --ollama, -o <url>: Ollama API URL (OLLAMA_HOST)
• --embedding, -e <model>: Ollama embedding model (EMBEDDING_MODEL)
• --qdrant-host, -qh <host>: Qdrant gRPC host (QDRANT_HOST)
• --qdrant-port, -qp <port>: Qdrant gRPC port (QDRANT_PORT)
• --exclude-dirs, -xd <list>: Comma-separated directory names to ignore (EXCLUDE_DIRS)
• --include-hidden-dirs, -ihd <list>: Comma-separated hidden directories to watch (INCLUDE_HIDDEN_DIRS)
• --parser-mode, -pm <mode>: Parsing mode: code, doc, or full (PARSER_MODE)
• --max-workers, -mw <number>: Max concurrent embedding workers (MAX_EMBEDDING_WORKERS)
• --batch-size, -bs <number>: Batch size for vector upserts (BATCH_SIZE, default: 100)
• --batch-timeout, -bt <duration>: Batch timeout for vector upserts (BATCH_TIMEOUT, default: 200ms)
• --log-to-file, -lf <bool>: Enable log output to physical file (LOG_TO_FILE, default: false, saved to .qdrant-mcp-server/qdrant-mcp-server.log)
• --search-mode, -sm <mode>: Vector search mode: dense, sparse, or hybrid (SEARCH_MODE, default: dense)

---

Core Codebase Reference Snippets for: "JWT token parsing middleware with custom claim validation"

#### [1] Function: ValidateCustomClaims in /home/user/Workspace/my-project/auth/middleware.go (Lines 12-32) (Match Score: 0.92 | Last Synced: 2026-05-23 09:28:10)

func ValidateCustomClaims(tokenString string) (*Claims, error) {
    // ...
}

#### [2] Doc Chunk (Page/Section 3) in /home/user/Workspace/my-project/docs/auth-specs.md (Match Score: 0.88 | Last Synced: 2026-05-23 09:28:10)

JWT token claims are validated against the current session lifecycle policy...

---

🔌 Integration with MCP Clients

To use this server with your favorite AI agent tool, add it to your client's MCP configuration settings.

Claude Desktop Integration

Add the following block to your claude_desktop_config.json (typically located at ~/.config/Claude/claude_desktop_config.json on Linux/macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "qdrant-rag": {
      "command": "/usr/local/bin/qdrant-mcp-server",
      "env": {
        "QDRANT_HOST": "172.20.0.5",
        "QDRANT_COLLECTION": "my-codebase-collection",
        "WATCH_DIRECTORY": "/home/user/Workspace/my-project",
        "OLLAMA_HOST": "http://127.0.0.1:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "EXCLUDE_DIRS": "node_modules,dist,bin,obj,.git",
        "INCLUDE_HIDDEN_DIRS": ".github"
      }
    }
  }
}

[!NOTE] - Direct Installer: If you installed using the one-line curl command, the path is /usr/local/bin/qdrant-mcp-server (or /home/<username>/.local/bin/qdrant-mcp-server if installed as a non-root fallback). - Manual Compilation: If you compiled it manually, specify the path where you saved the binary (e.g., /home/<username>/bin/qdrant-mcp-server or the absolute path to your working directory build).

Cursor & Windsurf Integration

1. Open your editor settings.
2. Navigate to MCP or Model Context Protocol settings.
3. Click Add New MCP Server.
4. Set the Type to command (or stdio).
5. Provide a name: qdrant-rag.
6. Provide the command: /usr/local/bin/qdrant-mcp-server (update this path to match your installation path: /usr/local/bin/qdrant-mcp-server, /home/<username>/.local/bin/qdrant-mcp-server, or /home/<username>/bin/qdrant-mcp-server depending on how you installed or built it).
7. Configure the environment variables list as shown in the JSON schema above.

---

What the Release Workflow Does:

• Verification: Automatically checks Go module dependencies and runs the Go test suites before any builds are triggered.
• Cross-Compilation: Compiles native binaries in parallel using a matrix strategy for multiple architectures:
• Linux: amd64, arm64
• macOS (Darwin): amd64, arm64
• Windows: amd64
• Dynamic Versioning: Injects the exact version tag inputted by the user at build time into the application binary using -ldflags="-X main.Version=<VERSION> -s -w".
• Packaging: Packs each compiled binary into .tar.gz archives (for Linux/macOS) and .zip archives (for Windows).
• GitHub Release & Assets: Automatically checks if the git tag exists (creates and pushes it if it does not), creates a new public GitHub release, generates release notes from recent commit history, and attaches all compressed archives as downloadable assets.

---