适合谁
- 希望数据和模型处理都在本地运行的用户
- 拥有 Markdown 文档、会议记录或代码文档集合的个人和团队
- 需要关键词搜索与语义搜索结合的 agent 工作流
Q
56FMRS · C
QMD 是功能完整的本地 Markdown 知识库 MCP 搜索服务器，提供关键词、语义和混合重排检索，以及单文档和批量文档读取。它适合本地 agent 工作流，但需要本地模型、索引存储和文件读取权限；HTTP 模式未提供认证。
QMD 是一个设备端文档搜索引擎，可索引 Markdown 笔记、会议记录、文档和知识库。它结合 BM25 全文搜索、向量语义搜索与本地 LLM 重排，并通过 MCP 提供查询、文档读取、批量读取和索引状态工具。
工具能力
query
使用词法、向量和 HyDE 子查询进行混合搜索，并通过 RRF 与本地 LLM 重排结果。
get
按路径、文档 ID 或行范围读取单个文档。
multi_get
按 glob 模式、逗号分隔的路径或文档 ID 批量读取文档。
status
查看索引健康状况和集合信息。
安装接入
安装 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"]}}}
选型与风险
不适合谁
- 需要云端托管、远程知识库同步或内置身份认证的用户
- 没有本地模型运行资源或无法下载 GGUF 模型的环境
- 需要搜索非已配置集合或非受支持文件内容的场景
所需权限
- 读取已配置集合中的文件以建立索引和返回文档内容
- 写入本地 QMD 配置、缓存、SQLite 索引和模型缓存目录
- 首次使用模型时访问 HuggingFace 下载 GGUF 模型；集合更新命令还可能执行配置的 shell 命令
风险与副作用
- HTTP 端点默认未认证；绑定到非本机地址时应在前面配置自己的认证层
- 索引可能包含个人笔记、会议记录或内部文档，需保护本地索引和 HTTP 访问
- 配置的集合更新命令会在集合目录中通过 bash 执行，失败时会中止后续更新
- 自定义本地配置可能引用项目外路径或自定义模型，非交互式环境会跳过未信任字段
常见排障
- 确认运行时为 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 的输出
使用场景
搜索个人 Markdown 笔记和知识库
检索会议记录与项目文档
为本地 AI agent 提供结构化文档检索
按路径或文档 ID 获取完整内容或指定行范围
支持客户端
Claude Desktop完整支持
Claude Code完整支持