Mortis-RAG-MCP
Mortis-RAG-MCP is a local RAG knowledge base MCP server for Obsidian/Markdown notes that lets you register, index, search, read, and manage vaults.
Register/unregister local folders as knowledge bases with persistent registry and file watching (
kb_init,kb_unregister).List registered vaults and set cross-vault retrieval weights (
kb_vaults,kb_set_weight).Export/import index snapshots for migration and force rebuilds (
kb_export,kb_import,kb_rebuild).List indexed Markdown files and view index health/stats (
kb_list,kb_stats).Perform hybrid semantic + keyword search across one or multiple vaults with filters (tags, path prefix, mtime), pagination, deduplication, reranking, and cross-vault grouping (
kb_search).Read original note content by source path, line range, or heading, with incremental sync (
kb_read).Manage RAG exemptions via ignore patterns or per-file frontmatter/ignore file (
kb_exempt).Per README, also supports private solo vaults, natural-language vault descriptions for routing, PDF/Office ingestion via MinerU, and alias/exact-term search.
Allows registering Obsidian-style Markdown vaults as knowledge bases, searching raw chunks across one or multiple vaults, reading specific notes or sections, and managing vault indexes and exclusions.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Mortis-RAG-MCP search my notes for 'RAG evaluation metrics' and show top results"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Mortis'RAG MCP
English | 简体中文
面向 Obsidian 与本地知识库的现代化 RAG(检索增强生成)MCP 服务。 纯标准库高能实现,源文件安全驻留本地;深度支持语义检索、跨模态以文搜图、虚拟文档库、多库智能路由与精准阅读。
🚀 当前版本:v0.9.1(修复与性能补丁)
v0.9.1 修复了「本机零成本推理端点被付费闸门误拦、导致索引长时间停摆」的问题,并显著提升大知识库下的检索与重建性能。面向付费端点的安全闸门行为保持不变。
🛡️ 零成本端点不再被误拦:指向回环地址(如
127.0.0.1)且未配置 API 凭据的端点不再进入付费台账,也不会被历史未决请求牵连;已计费风险一侧的 fail-closed 闸门一字未动。🔓 未决请求不再永久冻死索引:结果落账失败会补位重试一次;零成本端点上的
prepared请求超过租约后自动放行,可能已计费的submission_unknown仍需人工对账。🔎 堵点可观测:
kb_stats新增paid_route_blocked,指出每个请求类型当前被哪一条真正卡住(确有堵点时才出现)。⚡ 更快更省:单次检索的读库次数由 3 次降至 1 次(同步预热后实测 0 次)。本机同一脚本对照下,2,892 文档 / 9,316 切片规模
kb_search中位耗时 36.1 ms → 20.3 ms(探针相对口径,非跨环境保证);一次kb_rebuild只执行一轮全量同步(冷启动 3 → 1、温启动 2 → 1)。
Related MCP server: Smart Connections MCP Server
🏁 上一里程碑:v0.9.0(重大功能发布)
v0.9.0 迎来了架构级的全面跃迁,正式切换至商业友好的 Apache-2.0 开源许可,并带来以下核心突破:
🏢 全新虚拟文档库(Virtual Doc Store):外部文档(PDF/Word/PPT/Excel)解析产物默认入库底层虚拟文档系统,源文件零改写、原笔记目录零污染(不再生成
.mortis-parsed/镜像文件),内置代际管理、CAS 校验与段级原子断点续传。🖼️ 跨模态图文检索打通(Text-to-Image):打通多模态向量对齐空间,支持直接使用自然语言文本检索召回笔记中的插图与图表;新增
kb_read_media工具支持在受控预算(budget_bytes)内安全直读媒体(注:文字检索图片已跑通,部分外部客户端富媒体展示与特定付费端点装配尚未全量验收)。🧩 自适应 Token 估算切块(
estimated_tokens):新知识库默认启用 Token 粒度自适应切片,语义上下文更连贯完整;建库与检索支持独立{text}提示词模板注入;原生收录.markdown扩展名。🔄 工业级摄取重试与未决请求台账:
kb_ingest全新支持retry动作,失败/取消任务可精准断点续跑;CLI 新增--list-requests与--abandon-request管控未决请求意图。🧹 架构解耦与纯粹化(Breaking Change):彻底剔除重型且低频的外部 ffmpeg 音频转录链路,配置中残留的
[audio]字段自动静默兼容忽略;已有文本笔记索引与向量缓存 100% 平滑继承。🪟 Windows 平台加固与防死锁:彻底修复 UTF-8 BOM 配置文件被静默错解进而被 doctor 误判为 BROKEN 的陈年顽疾;重构读写并发锁,消除异步索引自排队假死。
完整变更细节与升级指引见 CHANGELOG_user.md。
🌟 核心特性
🖼️ 跨模态图文检索与媒体直读(0.9.0):支持多模态向量嵌入空间,支持以文搜图(Text-to-Image);新增
kb_read_media工具精准定位并按字节预算(budget_bytes)按需读取多媒体内容,杜绝上下文溢出。🏢 非侵入式虚拟文档库(0.9.0):外部复杂文档解析结果默认收敛至用户缓存层虚拟文档系统,保持本地笔记目录 100% 纯净,支持段级断点续传与多代版本原子恢复。
🧩 自适应 Token 估算切块与统一模板(0.9.0):基于 Token 估算的自适应语义切块(
estimated_tokens),长文本切分自然连贯;建库与查询支持统一与独立的{text}提示词模板定制。🔄 摄取断点重试与意图台账(0.9.0):
kb_ingest支持指定job_id对失败或取消的任务进行断点重试;CLI 随时查阅与管理未决任务,索引生命周期(index_state)多态解耦。⚡ 紧凑初筛与章节直读(0.8.1):新增
compact=true极简结构化投影与整块预算续页控制;kb_read支持按heading物理章节与小说分卷直读,附带行号越界精准诊断。📂 自由挂载,零路径绑定:通过
kb_init一键挂载任意本地文件夹为知识库,持久化注册表管理,不绑定死路径,换电脑或多库迁移极简。📖 切片原地展开与双链直读(0.8.0):命中切片后直接由
kb_read(chunk_id=...)原地展开上下文,省去手工换算行号;遇到[[双链]]引用直接按短名快速寻址阅读。🏷️ 别名检索与硬词保底(0.8.0):原生支持 Obsidian frontmatter
aliases别名;支持exact_terms专有名词硬包含保底,生僻术语与专有代号绝不漏召回。🛡️ 搜索预算控制与本地诊断(0.8.0):支持
budget_bytes字节硬预算,避免大搜索撑爆模型上下文或击穿客户端缓冲区;支持脱敏本地诊断日志。📚 库名直呼与多库定向(0.7.2):检索时可直接传库名(如
vault_path="我的笔记"),无需拼接 Windows 漫长路径;支持通过vault_paths数组同时指定多个目标库定向检索。🔍 轻量预览与二段式精读(0.7.2):支持
preview=true快速返回高光切片与行号,正文配合kb_read按需精准精读,大幅降低模型 Token 冗余。📄 多格式原生收录(.md / .txt / .markdown):纯文本
.txt(小说/分卷/资料)与.markdown与标准 Markdown 享有同等一等公民地位,支持小说章节标题自动识别。🔍 Agent 信任锚,免预检开箱即搜(0.7.1):一条
python -m mortis_rag_mcp --doctor生成本机环境凭证(STATUS.md)。AI 助手读到 ✅ 即不再做任何环境/依赖/key 预检,首次提问就直接检索,省掉每次调用前的反复试探。🎯 智能定向路由与权重分配(0.7.0):支持为知识库配置自然语言描述(
kb_describe),支持跨库检索权重调整(kb_set_weight),AI 检索时按意图精准选库。🔒 私密独立库(solo)隔离:支持注册独立私密库(
kb_init_solo),默认不参与跨库全局搜索,仅在显式指定时查询,妥善保护个人隐私。⚡ 混合检索与毫秒级增量同步:融合关键词全文检索(BM25/FTS)与语义向量召回,配合自动重排序;支持原生文件监听与读优先后台增量同步,笔记随写随搜。
📦 轻量纯粹,零沉重运行时依赖:核心功能纯标准库实现(
dependencies = []),轻量可靠,可选依赖(pymupdf、sqlite-vec等)按需热插拔。
🛠️ 完整工具一览(16 个核心 MCP 工具)
Mortis'RAG MCP 提供了 16 个标准化 MCP 工具,覆盖从知识库注册、混合检索、多模态直读到文档摄取与运维全生命周期:
1. 知识库挂载与多库管理
工具 | 用途说明 |
| 注册并挂载新知识库(指定物理文件夹路径与显示名称) |
| 注册/转换为私密独立库(默认排除在跨库盲搜外,仅显式指定时检索) |
| 查看当前已注册的全部知识库列表、路径与状态 |
| 设置知识库自然语言描述,引导 AI 按意图进行智能路由选库 |
| 设置指定知识库在跨库联合检索中的打分权重比重 |
| 从注册表移除知识库(安全操作,绝不删除本地实际笔记文件) |
2. 混合检索与原文精读
工具 | 用途说明 |
| 语义向量与关键词混合检索(支持跨库/多库定向、目录过滤、分页、 |
| 精准读取原文笔记(支持按物理文件路径、行号区间、切片编号 |
| (0.9.0 新增) 按版本( |
3. 文档摄取与外部格式解析
工具 | 用途说明 |
| 摄取并解析知识库内的 PDF / Office / 外部文档(支持 |
4. 状态浏览、豁免与维护备份
工具 | 用途说明 |
| 查看知识库文件数、切片数、向量模型与底层加速依赖状态 |
| 分页浏览知识库已收录的文件列表,支持目录前缀过滤 |
| 管理知识库豁免规则与单文件排除(即时生效,毫秒级响应) |
| 强制全量重新构建指定知识库的全文与向量索引 |
| 导出知识库配置、权重与元数据备份快照 |
| 从备份恢复知识库元数据,解耦反馈索引构建状态( |
🚀 5 分钟快速上手
1. 安装
环境要求:Python 3.10+。
git clone https://github.com/moton16/Mortis-RAG-MCP.git
cd Mortis-RAG-MCP
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .可选依赖:
本地 Office/PDF 解析支持:
pip install -e ".[docs]"磁盘向量数据库加速:
pip install -e ".[vec]"
2. 配置
从模板复制配置文件:
Copy-Item .\config\app.toml.example .\config\app.toml(1) 基础配置:Embedding API Key(用于笔记语义检索)
推荐使用免费档硅基流动 BAAI/bge-m3:
方式一(推荐):设置系统环境变量
MORTIS_RAG_API_KEY=你的API密钥(同时兼容旧名VAULT_MCP_API_KEY)。方式二:直接在
config/app.toml中配置你的服务商地址与密钥。
(2) 可选配置:MinerU 接入(用于 PDF / Office 文档解析摄取)
如果需要检索知识库内的 PDF、Word、PPT、Excel 文件:
打开
config/app.toml,在[ingest]小节将enabled = true。配置 MinerU Token(两种方式):
高精度通道(推荐):前往 mineru.net 免费获取 API Token,设置系统环境变量
MINERU_API_TOKEN=你的Token(或在config/app.toml的[ingest]中填写api_key = "你的Token"),享受每日 1000 页额度并支持文档插图提取。免登试用通道:留空
api_key即可直接使用(适合 20 页以内的日常小文档体验;该通道为轻量纯文本提取,不返回图片)。
3. 接入 AI 客户端
服务以标准 stdio 模式运行,直接在你的 MCP 客户端中配置即可:
WorkBuddy / 自定义 JSON 连接器
{
"mortis-rag-mcp": {
"command": "python",
"args": ["-m", "mortis_rag_mcp", "--serve-mcp-stdio", "--app-config", "C:\\你的路径\\config\\app.toml"],
"env": {
"MORTIS_RAG_API_KEY": "你的API密钥",
"MINERU_API_TOKEN": "可选,用于PDF解析的MinerU密钥"
}
}
}Codex / Trae / TOML 配置
[mcp_servers.mortis_rag_mcp]
command = "mortis-rag-mcp"
args = ["--serve-mcp-stdio", "--app-config", "C:\\你的路径\\config\\app.toml"]
enabled = true4. 初始化与使用
连接成功后,在对话中对 AI 助手说:
"帮我用
kb_init注册知识库:D:\我的笔记"
知识库即可在后台自动建立索引。之后只需自然提问:
"搜一下数电笔记里关于触发器的内容" "查一下知识库里关于项目架构的说明"
📚 详细文档与导航
📖 新手完整指南:详见 QUICKSTART_user.md(更详尽的安装排错、0.9 升级与恢复及配置项说明)。
📝 版本更新日志:详见 CHANGELOG_user.md(各版本详细更新说明与功能亮点)。
🤖 AI 助手配套技能:详见 skills/mortis-rag-mcp/SKILL.md(为智能体提供最佳检索路由纪律)。
💻 开发者技术说明书:详见 docs/PROJECT_GUIDE.md 与 docs/Quick-start_developer.md(底层架构设计、二次开发与技术流水)。
📄 License
本项目自 v0.9.0 起采用 Apache License 2.0 开源许可(v0.8.1 及更早版本仍为 MIT,已发布版本的历史授权不受影响)。
可选解析依赖(如 PyMuPDF)由用户自行安装,不在本项目的 Apache-2.0 授权范围内,各自的许可证见 NOTICE。
Available Tools
12 toolskb_exemptA
查看、添加、删除知识库的 RAG 豁免项(排除不希望被检索的私密/草稿内容)。支持查看规则、添加/删除 .vaultignore 通配符、标记/取消单个文件豁免、检查文件豁免状态。
Inputs: action (required), method, source, pattern, +1 more.
kb_exportA
把知识库的索引快照(chunks + 向量 + FTS)导出为 zip 文件,用于换机/换目录迁移,导入后无需全量重新 embedding。要求缓存已启用且完成过至少一次索引。
Inputs: out_path (required), vault_path.
kb_importA
从 kb_export 生成的快照恢复索引缓存(先 kb_init 注册目标目录再调用)。导入后的下一次同步应当 0 次 embedding 调用;快照的向量模型/维度与本机配置不一致时拒绝,除非 force=true(此时只导入文本层并本地重嵌)。
Inputs: snapshot (required), force, vault_path.
kb_initA
注册(初始化)一个文件夹为知识库:校验目录、写入用户级注册表(跨重启保留)、后台建立索引并启动文件监听。首次使用或要纳入新文件夹时调用。
Inputs: path (required), name.
kb_listB
列出已索引的 Markdown 文件。可传 vault_path 指定知识库。
Inputs: vault_path.
kb_readA
读取知识库原文(不调用 LLM 生成回答;若索引有未同步的变更会先触发一次增量同步,可能调用 embedding API,建议带上 start_line/end_line 限定范围避免一次拉全篇)。多库环境下建议显式传 vault_path(fan-out 结果中的 source 是库内相对路径)。
Inputs: source (required), heading, end_line, start_line, +1 more.
kb_rebuildA
删除指定知识库的磁盘缓存并强制全量重建索引(首次建库或内容大改后用)。
Inputs: vault_path.
kb_searchA
搜索知识库并返回结构化原始 chunks。不传 vault_path 时跨全部注册库 fan-out 检索(结果带 vault 字段)。
Inputs: query (required), tags, limit, top_k, +8 more.
kb_set_weightA
设置知识库的检索权重:跨库检索时该库所有 chunk 的分数会乘以该系数,用于表达"这个库更重要"(默认 1.0,取值 0 < w <= 100)。
Inputs: weight (required), vault_path (required).
kb_statsB
返回指定知识库的索引状态、失败文件、最后同步时间和模型信息。
Inputs: vault_path.
kb_unregisterA
注销一个已注册的知识库:停止文件监听并从注册表移除(不影响文件夹本身)。
Inputs: path (required), purge_cache.
kb_vaultsA
列出所有已注册的知识库(含存活状态与索引进度)。
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 12 tools
Each tool targets a distinct operation in the RAG knowledge-base lifecycle: init/unregister manage registration, export/import handle snapshots, search/read retrieve content, and stats/vaults/exempt cover status and filtering. Even similar actions like rebuild and import are clearly separated by purpose and described preconditions.
Tools consistently use a kb_ prefix and short snake_case names, with clear verb-style commands like kb_init, kb_search, and kb_export. Minor deviations exist: kb_vaults and kb_stats are noun-style rather than verb-based, and kb_exempt covers multiple exemption-related actions rather than a single operation.
The 12 tools are well-scoped for a RAG knowledge-base management server, covering registration, indexing, migration, search, reading, statistics, weighting, and exemptions. Each tool serves a distinct and necessary role without bloat or redundancy.
The tool surface covers the core lifecycle well: registering, listing, searching, reading, exporting/importing, rebuilding, unregistering, and managing exemptions are all present. A minor gap is the lack of an explicit manual sync command, though file watching and read-triggered incremental sync largely mitigate this.
Maintenance
Related MCP Connectors
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides always-fresh semantic search over Obsidian vaults, automatically watching file changes and using local embeddings via Ollama.67 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables semantic search and related-note discovery across an Obsidian vault via MCP, providing RAG context blocks for natural language queries.-
- AlicenseBqualityBmaintenanceEnables local hybrid search over Obsidian and Markdown vaults via MCP, combining vector retrieval, full-text search, reranking, graph navigation, and safe CRUD while keeping data local.431MIT
- AlicenseBqualityCmaintenanceEnables hybrid dense and BM25 search over a markdown vault, with tools for reading, writing, grepping, and managing notes through any MCP-compatible client.12MIT