Skip to main content
Glama
deenesjakoruzh
michal7kw

qdrant-mcp-ollama

by michal7kw
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

qdrant-mcp-ollama

一个用于 Qdrant 向量数据库的 Model Context Protocol (MCP) 服务器，使用 Ollama 提供 GPU 加速的嵌入 功能。

为什么不用官方的 mcp-server-qdrant？

官方 Qdrant MCP 服务器 使用 FastEmbed 进行嵌入，但它存在以下问题：

  • 仅依赖 CPU 运行 — 在处理大型代码库时速度较慢，无法充分利用现代 GPU

  • 使用小模型（all-MiniLM-L6-v2，384 维）— 嵌入质量较低

  • 本地模式下存在单进程锁 — 同一时间只能有一个 MCP 客户端访问数据库

本服务器可以解决以上三个问题：

官方 mcp-server-qdrant

qdrant-mcp-ollama

嵌入引擎

FastEmbed（CPU）

Ollama（GPU）

默认模型

all-MiniLM-L6-v2（384 维，80MB）

bge-m3（1024 维，1.2GB）

并发访问

否（本地模式）

是（Qdrant 服务器）

模型灵活性

仅 FastEmbed 模型

任意 Ollama 嵌入模型

Related MCP server: Claude Context MCP

架构

┌──────────────┐     ┌────────────────────┐     ┌─────────────┐
│  MCP Client   │────>│  qdrant-mcp-ollama │────>│   Ollama    │
│ (Claude Code, │     │    (server.py)      │     │  (GPU)      │
│  Kilo Code,   │<────│                    │     └─────────────┘
│  Cursor, etc) │     └────────┬───────────┘
└──────────────┘              │
                              v
                   ┌────────────────────┐
                   │   Qdrant Server    │
                   │  (Docker, :6333)   │
                   │  Storage: local    │
                   │  disk / cloud      │
                   └────────────────────┘

前置要求

  • Ollama — 已安装并正在运行，且已拉取嵌入模型

  • Docker — 用于运行 Qdrant 服务器

  • uv — Python 包管理器（推荐）或 pip

快速开始

1. 在 Ollama 中拉取嵌入模型

ollama pull bge-m3

2. 启动 Qdrant 服务器

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

3. 运行 MCP 服务器

# No install needed — uv downloads dependencies on-the-fly:
QDRANT_URL="http://localhost:6333" \
EMBEDDING_MODEL="bge-m3" \
uv run --with fastmcp --with qdrant-client --with httpx python server.py

4. 嵌入一个代码库

uv run --with qdrant-client --with httpx python embed_codebase.py \
  /path/to/your/project my-project --preset python

5. 在 MCP 客户端中搜索

配置完成后（详情见下文），向你的 AI 助手提问：

“搜索代码库中的认证逻辑”

它将使用 qdrant_find 工具返回语义相关的代码片段。

设置 Qdrant 服务器

方案 A：Docker（推荐）

将数据存储在指定驱动器上（例如 Windows 下的 E:）：

# Create storage directories
mkdir -p E:/qdrant-storage E:/qdrant-snapshots

# Start Qdrant with persistent storage
docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v E:/qdrant-storage:/qdrant/storage \
  -v E:/qdrant-snapshots:/qdrant/snapshots \
  --restart unless-stopped \
  qdrant/qdrant:latest

在 Linux/macOS 上：

docker run -d --name qdrant-server \
  -p 6333:6333 -p 6334:6334 \
  -v ~/qdrant-storage:/qdrant/storage \
  --restart unless-stopped \
  qdrant/qdrant:latest

--restart unless-stopped 标志可确保 Qdrant 随 Docker Desktop 自动启动。

验证它是否正在运行：

docker ps --filter name=qdrant-server
# Or open http://localhost:6333/dashboard in your browser

方案 B：Qdrant Cloud

在 cloud.qdrant.io 注册，获取你的 URL 和 API 密钥。然后设置：

QDRANT_URL="https://your-cluster.cloud.qdrant.io:6333"
QDRANT_API_KEY="your-api-key"

注意： QDRANT_API_KEY 环境变量会自动传递给 Qdrant 客户端。

嵌入代码库

embed_codebase.py 脚本会扫描一个目录，将源文件分块，并通过 Ollama 将它们批量嵌入 Qdrant。

基本用法

uv run --with qdrant-client --with httpx python embed_codebase.py <directory> <collection-name>

使用扩展名预设

# Python project
python embed_codebase.py ./my-api api-backend --preset python

# Full-stack web project
python embed_codebase.py ./my-app frontend --preset web

# R / bioinformatics project
python embed_codebase.py ./analysis bio-analysis --preset r

# Everything
python embed_codebase.py ./mono-repo all-code --preset all

自定义扩展名

python embed_codebase.py ./project my-collection --extensions .py .sql .sh .yaml

可用预设

预设

扩展名

python

.py .pyi

javascript

.js .jsx .mjs .cjs

typescript

.ts .tsx

web

.js .jsx .ts .tsx .vue .svelte .html .css .scss

r

.R .r .Rmd .rmd

java

.java

csharp

.cs

go

.go

rust

.rs

cpp

.cpp .hpp .cc .hh .c .h

all

所有常见源码扩展名

如果没有提供 --preset 或 --extensions，脚本会自动检测文件类型。

所有选项

usage: embed_codebase.py <directory> <collection> [options]

positional arguments:
  directory              Path to the codebase directory
  collection             Qdrant collection name

options:
  --extensions EXT [EXT ...]  File extensions to include (e.g. .py .ts)
  --preset PRESET             Use a preset group of extensions
  --model MODEL               Ollama embedding model (default: bge-m3)
  --qdrant-url URL            Qdrant server URL (default: http://localhost:6333)
  --ollama-url URL            Ollama server URL (default: http://localhost:11434)
  --chunk-size N              Max lines per chunk (default: 80)
  --chunk-overlap N           Overlap lines between chunks (default: 10)
  --batch-size N              Upload batch size for Qdrant (default: 500)
  --append                    Append to existing collection instead of replacing

追加模式

默认情况下，重新运行脚本会替换现有集合。使用 --append 可向现有集合追加数据：

# First embed
python embed_codebase.py ./src main-code --preset typescript

# Add more files later
python embed_codebase.py ./docs main-code --extensions .md --append

多代码库用法

为每个代码库使用独立的集合，以保持搜索范围聚焦和相关：

# Project A
python embed_codebase.py ~/projects/api-server api-server --preset python

# Project B
python embed_codebase.py ~/projects/web-app web-app --preset web

# Project C
python embed_codebase.py ~/projects/data-pipeline data-pipeline --preset python

配置 MCP 服务器时：

  • 不设置 COLLECTION_NAME：必须在每次查询时指定集合名称。这适合一个 MCP 服务器服务于多个项目的情况。

  • 设置 COLLECTION_NAME：将自动使用默认集合。如果 MCP 客户端支持项目级配置，请为每个项目单独设置。

配置 Claude Code

添加 MCP 服务器

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

将 /path/to/qdrant-mcp-ollama/ 替换为你克隆此仓库的实际路径。

使用默认集合

如果你主要在一个项目上工作：

claude mcp add qdrant -s user \
  -e QDRANT_URL="http://localhost:6333" \
  -e OLLAMA_URL="http://localhost:11434" \
  -e EMBEDDING_MODEL="bge-m3" \
  -e COLLECTION_NAME="my-project" \
  -- uv run --with fastmcp --with qdrant-client --with httpx \
     python /path/to/qdrant-mcp-ollama/server.py

验证

claude mcp list
# Should show: qdrant: ... ✓ Connected

claude mcp get qdrant
# Shows full configuration details

在 Claude Code 中使用

配置完成后，Claude Code 可以使用以下工具：

  • qdrant_store — 存储信息：“在 Qdrant 中存储此认证模式”

  • qdrant_find — 搜索：“查找与数据库迁移有关的代码”

对于多代码库设置（无默认集合），请指定集合名称：

“在 api-server 集合中搜索限流逻辑”

配置 Kilo Code（VS Code 扩展）

Kilo Code 是一个内置 MCP 支持的 VS Code 扩展。

方案 1：手动配置 MCP

  1. 在 VS Code 中打开 Kilo Code 设置

  2. 导航到 MCP 服务器配置

  3. 添加新服务器：

字段 名称

值

Name

qdrant

Command

uv

Arguments

run --with fastmcp --with qdrant-client --with httpx python /path/to/server.py

  1. 设置环境变量：

变量 变量

值

QDRANT_URL

http://localhost:6333

OLLAMA_URL

http://localhost:11434

EMBEDDING_MODEL

bge-m3

COLLECTION_NAME

你的项目的集合名称（例如 my-project）

方案 2：VS Code settings.json

添加到你的 VS Code settings.json 中（Ctrl+Shift+P > Preferences: Open User Settings (JSON)）：

{
  "kilocode.mcpServers": {
    "qdrant": {
      "command": "uv",
      "args": [
        "run", "--with", "fastmcp", "--with", "qdrant-client", "--with", "httpx",
        "python", "/path/to/qdrant-mcp-ollama/server.py"
      ],
      "env": {
        "QDRANT_URL": "http://localhost:6333",
        "OLLAMA_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "bge-m3",
        "COLLECTION_NAME": "my-project"
      }
    }
  }
}

按项目配置 Kilo Code

对于多代码库设置，请在项目范围（而非全局）内配置 Kilo Code，并为项目指定 COLLECTION_NAME。这样每个工作区只会搜索自己的代码库。

配置其他 MCP 客户端

Cursor / Windsurf

为了支持远程客户端，请使用 SSE 传输方式运行服务器：

QDRANT_URL="http://localhost:6333" \
OLLAMA_URL="http://localhost:11434" \
EMBEDDING_MODEL="bge-m3" \
FASTMCP_PORT=8000 \
uv run --with fastmcp --with qdrant-client --with httpx \
  python server.py --transport sse

然后在 Cursor/Windsurf 的 MCP 设置中连接：http://localhost:8000/sse

通用 MCP 客户端（stdio）

默认传输方式为 stdio。任何支持 stdio 的 MCP 客户端都可以通过运行以下命令来使用本服务器：

uv run --with fastmcp --with qdrant-client --with httpx python server.py

配置参考

MCP 服务器环境变量

字段 字段

描述

默认值

QDRANT_URL

Qdrant 服务器 URL

http://localhost:6333

QDRANT_API_KEY

Qdrant Cloud 的 API 密钥

None

OLLAMA_URL

Ollama 服务器 URL

http://localhost:11434

EMBEDDING_MODEL

Ollama 嵌入模型名称

bge-m3

COLLECTION_NAME

默认集合（为空时必须在每次调用中指定）

(空)

选择嵌入模型

以下所有模型均可通过 ollama pull <model> 获取：

模型

维度

大小

速度

质量

适用场景

bge-m3

1024

1.2 GB

中等

高

通用、多语言

nomic-embed-text

768

274 MB

快

良好

轻量、面向英文

mxbai-embed-large

1024

670 MB

中等

高

英文、高质量

snowflake-arctic-embed2

1024

1.2 GB

中等

非常高

英文、最佳质量

all-minilm

384

46 MB

极快

一般

资源占用最小

建议： 从 bge-m3 开始。它能很好地处理代码，支持多语言内容（任意语言的注释），并且兼顾质量与速度。

重要： 用于索引集合的嵌入模型必须与用于查询的模型匹配。如果你使用不同的模型重新嵌入，请删除并重新创建集合。

GPU 利用率

更大的模型会占用更多 GPU 资源。如果你的 GPU 利用率不高：

  • 从 nomic-embed-text（274 MB）切换到 bge-m3（1.2 GB）或更大的模型

  • 嵌入脚本会将所有文本一次性发送到单个批次中，以最大化 GPU 利用率

  • 对于单个查询（通过 qdrant_find），GPU 峰值是短暂且正常的 — 嵌入单个查询只需要毫秒级的时间

查看 GPU 使用情况：nvidia-smi（NVIDIA）或 rocm-smi（AMD）

MCP 工具

qdrant_store

在 Qdrant 数据库中存储信息。

参数

类型

必填

描述

information

string

是

用于存储和可搜索的文本

collection_name

string

如果没有默认集合

Target collection

metadata

dict

否

可选元数据

qdrant_find

使用语义相似度搜索相关信息。

参数

类型

必填

描述

query

string

是

自然语言搜索查询

collection_name

string

如果没有默认集合

要搜索的集合

top_k

int

否

返回的最大结果数（默认值：5）

故障排除

“Connection closed” / MCP 服务器无法启动

  • Ollama 是否正在运行？ 使用 ollama list 检查。如有需要，运行 ollama serve 启动它。

  • 是否已拉取嵌入模型？ 运行 ollama pull bge-m3。

  • Qdrant 是否正在运行？ 使用 docker ps --filter name=qdrant-server 检查。

“Collection does not exist”

集合由嵌入脚本创建，或在首次调用 qdrant_store 时创建。可以这样做：

  • 先运行 embed_codebase.py 为你的代码库建立索引

  • 或通过 qdrant_store 存储内容，以自动创建集合

维度不匹配错误

这种情况发生在集合创建的嵌入模型与你查询所用模型不一致时。解决方法：

  1. 删除集合：访问 http://localhost:6333/dashboard

  2. 使用正确的模型重新嵌入

  3. 确保 MCP 服务器配置中的 EMBEDDING_MODEL 与你用于嵌入的模型一致

“存储文件夹已被另一个实例访问”

该错误来自 官方 mcp-server-qdrant 使用本地模式（QDRANT_LOCAL_PATH）时的情况。本项目通过 URL 连接 Qdrant 服务器来避免此问题。请确保你没有同时运行两个指向同一本地路径的服务器。

嵌入速度慢 / GPU 利用率低

  • 使用更大的模型：bge-m3（1.2 GB）而不是 nomic-embed-text（274 MB）

  • 嵌入脚本会一次将所有文本放在一个批次中发送——如果你有成千上万个分块，这样可以最大化 GPU 使用

  • 对于非常大的代码库（10,000 个以上文件），建议按目录拆分为多次运行

许可证

Apache License 2.0 — 参见 LICENSE。

Available Tools

2 tools
qdrant_findC

Search for relevant information in the Qdrant database using semantic similarity.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYesNatural language query to search for. The query is embedded using the same GPU model used for storage, ensuring accurate results.
top_kNoMaximum number of results to return (default: 5).
collection_nameNoName of the collection to search in. Required if no default collection is configured.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It implies a read-only operation but does not explicitly state that no data is modified, does not mention return behavior, error conditions, or limitations. The single sentence provides minimal behavioral disclosure beyond the literal action.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no redundancy or filler. It is front-loaded with the verb and resource. While extremely brief, it is not a tautology and conveys the essential purpose. It avoids unnecessary words while being clear.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has a sibling (qdrant_store) and an output schema (which covers return format), the description is still incomplete. It lacks any usage context, such as when to choose this over storage or how the search integrates with the workflow. The presence of an output schema reduces the need to explain returns, but the description does not cover the selection decision or behavioral expectations.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers all three parameters (query, top_k, collection_name) with descriptions, so the baseline is 3. The description adds nothing beyond the schema; it mentions 'semantic similarity' which is already implied by the query parameter's embedding mention. No additional value is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Search'), the target resource ('Qdrant database'), and the method ('semantic similarity'). This distinguishes it from the sibling qdrant_store, which likely stores information. However, it does not explicitly name the sibling or contrast with it, so it lacks the full differentiation seen in higher-scoring examples.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus the alternative qdrant_store, nor any mention of prerequisites or context. The description only states the action without any direction on selection or exclusion criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

qdrant_storeC

Store information in the Qdrant database with GPU-accelerated embeddings.

ParametersJSON Schema
NameRequiredDescriptionDefault
metadataNoOptional metadata dictionary to attach to the stored point.
informationYesThe text information to store. This will be embedded and made searchable via semantic similarity.
collection_nameNoName of the collection to store in. Required if no default collection is configured.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states that information will be stored with embeddings, but does not disclose potential side effects such as whether existing points are overwritten, whether collections are auto-created, or any error behavior. The mutation is implied but not explicitly flagged.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that conveys the core action. 'GPU-accelerated embeddings' adds a performance detail that may be useful context, but it could be considered extraneous. Overall, it is appropriately sized and front-loaded with the action.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple store operation with only 3 parameters and an output schema present, the description covers the basic action. However, it omits guidance on when a collection_name is required and does not mention any setup steps or constraints. It meets a minimum viable level but leaves gaps that an agent might need to handle.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific detail beyond what the schema already provides. The only minor addition is implying that information gets embedded, which is already stated in the schema. This meets the baseline but does not exceed it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Store information in the Qdrant database') with a specific resource and purpose. It implies a write operation distinct from the sibling qdrant_find, though it doesn't explicitly differentiate. The mention of 'GPU-accelerated embeddings' adds implementation detail but doesn't obscure the core purpose.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus the sibling qdrant_find. The description does not say 'use this to add data, use qdrant_find to search' or mention any prerequisites like collection existence. An agent would have to infer usage from the name alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv0.1.0
    • First observedqdrant_find
    • First observedqdrant_store
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.2/5.0

Scored across 2 tools

Disambiguation5/5

The two tools, qdrant_store and qdrant_find, have entirely distinct purposes—one writes data, the other retrieves it. There is zero ambiguity between them.

Naming Consistency5/5

Both tools follow a consistent 'qdrant_<verb>' pattern, using clear action verbs (store, find). The naming is predictable and uniform.

Tool Count3/5

With only two tools, the server feels thin for what is typically a database domain, but it is not an extreme mismatch. It sits at the borderline of adequacy.

Completeness2/5

The server only provides store and find, lacking any management operations like delete, update, or list. For a database, this is a significant gap that will limit workflow coverage.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers