← 返回目录

QMD MCP Server

官方

在本地搜索 Markdown 知识库的混合搜索引擎。

查看安装方法 ↓ 横向对比 GitHub 源仓库 ↗

分类: 开发工具第 176 / 438
Stars: ★ 30.3k 非常热门
传输方式: stdio（本地进程） · Streamable HTTP
运行环境: Node.js 22+ · Bun 1.0.0+
凭据: 无需凭据
许可证: MIT
最近提交: 6 天前
工具数: 4

56FMRS · C

QMD 是功能完整的本地 Markdown 知识库 MCP 搜索服务器，提供关键词、语义和混合重排检索，以及单文档和批量文档读取。它适合本地 agent 工作流，但需要本地模型、索引存储和文件读取权限；HTTP 模式未提供认证。

最强项 · 文档质量 15/20 最弱项 · 维护活跃度 8/20

可靠性

9/20

安全与权限

11/20

维护活跃度

8/20

文档质量

15/20

安装易用性

13/20

查看各项评分依据

可靠性 9/20: README 明确列出 MCP 初始化后提供的 query、get、multi_get、status 工具及参数，且描述了 stdio 与 HTTP 传输、索引依赖和若干错误边界，因此主流程可行性较高。但未提供已缓存 manifest、源码、CI 或提交测试证据；未知参数会被静默忽略，模型首次下载和本地索引状态也可能导致不可诊断失败。按静态评审规则，证据不足且没有关键路径测试，扣分并不得超过 12 分。
安全与权限 11/20: 默认 stdio 仅访问本机配置的索引目录，且项目本地配置中的外部路径、更新命令和自定义模型有信任门控；HTTP 默认绑定 localhost，并有 Origin/Host 校验，安全边界有明确说明。但 HTTP 端点无认证，使用 0.0.0.0 时主机校验会跳过，且允许通过环境变量关闭校验；配置的 update 命令通过 bash 执行，MCP/CI 场景会跳过需审批字段而继续运行。未见凭据窃取或恶意默认行为，但权限、认证和远程暴露仍不完整，因此扣分。
维护活跃度 8/20: 项目声明 MIT 许可证，并给出仓库、CHANGELOG 和明确的配置及模型更新路径，显示出一定维护基础。可是提示材料没有提供发布记录、提交频率、依赖更新、CI、漏洞响应渠道或维护者承诺；星数和 issue 数不能加分。因此只能给出中低分。
文档质量 15/20: README 覆盖安装、客户端配置、stdio/HTTP、工具参数、返回格式、索引、模型、环境变量、边界行为、信任机制、限制和示例，且明确披露无认证 HTTP 端点、模型下载及资源要求。扣分点是 manifest 未缓存、缺少可核验的源码/测试证据，部分 SDK 示例与 MCP 参数命名存在差异，且成本、故障诊断和版本兼容证据不充分。
安装易用性 13/20: 提供 npm、Bun、npx/bunx 安装方式，包含 Claude Desktop 和 Claude Code 配置示例，也说明 Node/Bun、SQLite、模型下载和 HTTP 地址要求，完成连接的路径清晰。扣分原因是需要 Node 22/Bun、macOS 可能需要 Homebrew SQLite，首次自动下载约 2GB 模型，索引和 embedding 还需额外步骤；未证明其他主流客户端兼容性或存在 CI 验证。

静态评测 · 未实际运行收录于 2026-08-14

查看 FMRS 评分方法 →

选型与风险

能访问什么读取本地文件连接数据库

适合谁

希望数据和模型处理都在本地运行的用户
拥有 Markdown 文档、会议记录或代码文档集合的个人和团队
需要关键词搜索与语义搜索结合的 agent 工作流

不适合谁

需要云端托管、远程知识库同步或内置身份认证的用户
没有本地模型运行资源或无法下载 GGUF 模型的环境
需要搜索非已配置集合或非受支持文件内容的场景

所需权限

读取已配置集合中的文件以建立索引和返回文档内容
写入本地 QMD 配置、缓存、SQLite 索引和模型缓存目录
首次使用模型时访问 HuggingFace 下载 GGUF 模型；集合更新命令还可能执行配置的 shell 命令

风险与副作用

HTTP 端点默认未认证；绑定到非本机地址时应在前面配置自己的认证层
索引可能包含个人笔记、会议记录或内部文档，需保护本地索引和 HTTP 访问
配置的集合更新命令会在集合目录中通过 bash 执行，失败时会中止后续更新
自定义本地配置可能引用项目外路径或自定义模型，非交互式环境会跳过未信任字段

安装接入

准备工作

运行环境：Node.js 22+ · Bun 1.0.0+

其他可选配置项（11 个）

QMD_EMBED_MODEL 可选覆盖默认 embedding 模型的 HuggingFace GGUF URI，适合多语言（CJK）语料，切换后需运行 qmd embed -f。

QMD_ALLOWED_ORIGINS 可选 HTTP 传输下额外允许的 Origin（逗号分隔），设为 * 可禁用检查；用于非回环访问场景。

QMD_ALLOWED_HOSTS 可选 HTTP 传输下额外允许的 Host 头值（逗号分隔），--host 0.0.0.0 时可用来重新启用主机校验。

QMD_HOST 可选覆盖 HTTP 服务器默认绑定地址（默认 localhost）。

QMD_CONFIG_DIR 可选覆盖配置目录位置（默认 ~/.config/qmd），index.yml 所在处。

QMD_LLAMA_GPU 可选强制 llama.cpp GPU 后端（metal/vulkan/cuda）或设为 false 禁用 GPU。

QMD_FORCE_CPU 可选设为 1/true 强制 CPU 模式，等价于 --no-gpu。

QMD_EMBED_PARALLELISM 可选覆盖 embedding/reranking 上下文并行度（1-8），Windows CUDA 默认 1。

QMD_EDITOR_URI 可选终端结果可点击链接的编辑器 URI 模板，如 vscode://file/{path}:{line}:{col}。

QMD_TRUST_LOCAL_CONFIG 可选设为 1 允许 CI/MCP 场景下无人值守采用项目本地 .qmd/index.yml 的受限字段。

QMD_TRUST_UPDATE_HOOKS 可选设为 1 允许 CI/MCP 场景下无人值守运行项目配置中的 update 命令。

安装 Node.js 22 或更高版本，运行 npm install -g @tobilu/qmd，然后在 Claude Desktop 的配置文件中加入 install_config 中的配置并重启客户端。首次使用语义搜索或混合搜索时，QMD 会下载并缓存本地 GGUF 模型。也可运行 qmd mcp --http，并将 MCP 客户端连接到 http://localhost:8181/mcp。

claude_desktop_config.json

{"mcpServers":{"qmd":{"command":"qmd","args":["mcp"]}}}

以 Claude Desktop 为例。其他客户端的配置文件位置或字段可能不同（如 VS Code 使用 servers 字段），可用下方配置生成器转换。

.vscode/mcp.json

{
  "servers": {
    "qmd": {
      "command": "qmd",
      "args": [
        "mcp"
      ]
    }
  }
}

写入项目的 .vscode/mcp.json（VS Code 使用 servers 字段）。

Terminal

claude mcp add qmd -- qmd mcp

在终端运行；先把 <…> 占位符换成你自己的值。

生成并校验客户端配置

验证是否装好

安装并执行 qmd embed 索引后，在客户端中确认工具列表出现 query、get、multi_get、status 四个工具，然后调用 status 查看索引信息即证明连接成功。

常见排障

确认运行时为 Node.js 22 或更高版本，或 Bun 1.0.0 或更高版本
先运行 qmd collection add 配置集合，再运行 qmd update；语义搜索前运行 qmd embed
macOS 上如遇 SQLite 扩展问题，安装 Homebrew SQLite
HTTP 连接问题检查端口、绑定地址、Origin 和 Host 校验；对外暴露时配置 QMD_ALLOWED_ORIGINS 或 QMD_ALLOWED_HOSTS，并自行提供认证
查询范围必须使用 collections 数组；单数 collection 参数会被静默忽略
检查模型是否已下载、GPU/CPU 设置以及 qmd status 或 qmd doctor 的输出

试试这样问

连接成功后，可以直接对 AI 助手这样说：

用 query 工具在我的笔记里搜索“authentication flow”，限制返回 5 条结果
帮我取回文档 docs/api-reference.md 的完整内容
用 multi_get 批量读取 journals/2025-05*.md 匹配的所有文档
运行 status 看看索引健康状况和已配置的 collection

工具能力 4

query 只读

使用词法、向量和 HyDE 子查询进行混合搜索，并通过 RRF 与本地 LLM 重排结果。

get 只读

按路径、文档 ID 或行范围读取单个文档。

multi_get 只读

按 glob 模式、逗号分隔的路径或文档 ID 批量读取文档。

status 只读

查看索引健康状况和集合信息。

使用场景

搜索个人 Markdown 笔记和知识库

检索会议记录与项目文档

为本地 AI agent 提供结构化文档检索

按路径或文档 ID 获取完整内容或指定行范围

支持客户端

Claude Desktop

Claude Code

依据项目文档列出，未经本站实测。

详细介绍

QMD 是一个设备端文档搜索引擎，可索引 Markdown 笔记、会议记录、文档和知识库。它结合 BM25 全文搜索、向量语义搜索与本地 LLM 重排，并通过 MCP 提供查询、文档读取、批量读取和索引状态工具。