Obsidian Vault MCP

io.github.luffysolution-svg由 GitHub 帳號 luffysolution-svg 發布v3.0.2更新於 Oct 24, 2026

Local Zotero, MinerU, Obsidian literature workflow with transactional Analysis notes.

已驗證STDIO僅桌面效率與工作流檔案與儲存知識與記憶

概覽

AI 產生的概覽

本地 MCP 服務，把 Zotero、MinerU 與 Obsidian 儲存庫串成可追溯的文獻研究工作流，並產生結構化 Analysis 筆記。

可以做什麼
  • 查詢 Zotero 條目、Collection、筆記、註解與 BibTeX，並匯入或同步到儲存庫
  • 用 MinerU 將 PDF 解析為 Markdown，每篇文獻使用獨立圖片目錄與相對連結
  • 維護 Obsidian 文獻主筆記、索引與 base 檢視，以及跨文獻的可追溯 Wiki
  • 建立並驗證五類 Analysis 筆記：精讀、綜述、段落問答、圖表問答、概念
  • 以交易方式寫入，支援 dry-run、暫存、鎖定、備份、預覽與回滾
  • 提供版本與設定檢查，並可安裝用戶端外掛與 7 個科研 Skills
適用情境
適合以 Zotero 管理來源、以 Obsidian 沉澱筆記的研究人員與學生，希望助理在儲存庫內匯入文獻、解析全文、針對段落或圖表作答、比較論文並撰寫文獻綜述。
執行需求
以 Python 3.10+ 套件在本機透過 stdio 執行（uv、uvx、pipx 或 pip）。需要 OBSIDIAN_VAULT_PATH 指向已由 Obsidian 開啟且含 .obsidian 目錄的儲存庫。Zotero 相關工具需啟動 Zotero Desktop 並啟用本機 API；PDF 解析需 MinerU，可能需要 token。未宣告 MCP 層認證。
安裝前請注意
會寫入儲存庫：筆記、索引、附件與 Analysis 檔案，建議先 dry-run 並保存 transactionId。不要提交儲存庫絕對路徑、Zotero 資料目錄、MinerU token 或其他憑證。MinerU 可能將 PDF 傳送到外部服務，使用前請確認授權與組織政策。建議使用本機 stdio；SSE/HTTP 須置於可信任的認證邊界之後。交易備份不能取代獨立的儲存庫備份。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Obsidian Vault MCP，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

Obsidian Vault MCP

面向科研文献工作流的本地 MCP 服务：以 Zotero 管理来源，以 MinerU 提取全文，以 Obsidian 沉淀文献、Wiki 与结构化 Analysis，并通过 Skills 让 AI Agent 按可追溯流程工作。

English · 完整安装教程 · 开发文档 · 更新日志 · 贡献者

架构

text
用户自然语言任务        ↓7 个科研 Skills：识别意图、规划步骤、约束证据与输出        ↓31 个 MCP Tools：版本契约、查询、导入、解析、检索、校验与事务写入        ↓Zotero Desktop ── PDF ── MinerU ── Obsidian Vault                                      ├─ Literature 主笔记                                      ├─ PDF 与全文 Markdown                                      ├─ Index / Literature.base                                      ├─ Wiki                                      └─ 五类 Analysis / Analysis.base

项目不绑定大模型供应商。MCP Tools 负责确定性的本地数据操作，Skills 负责把工具编排成可复用的科研工作流。

核心功能

  • 稳定文献身份：以 Zotero 父条目 zoteroKey 作为主键。
  • Zotero 导入与同步：支持单篇、Collection、notes、annotations、BibTeX、存储附件和链接附件。
  • MinerU 全文解析：将 PDF 规范化为 Markdown，每篇文献使用独立图片目录和相对链接。
  • Obsidian 文献库：自动维护 Literature/index.md、Literature/Literature.base、主笔记、PDF、全文和 Wiki。
  • 结构化研究层：支持 full_read、literature_review、passage_qa、figure_qa、concept 五类 Analysis。
  • 统一数据库视图：Literature/Analysis/Analysis.base 提供 9 个视图。
  • 科研 Skills：内置 paper-qa、full-read、passage-qa、figure-qa、compare-papers、literature-review、concept-learning。
  • 安全写入：支持 dry-run、staging、锁、备份、原子替换、事务预览和回滚。
  • 版本可验证：literature_version 返回当前版本、31 个工具、7 个 Skills 和五类 Analysis。
  • 多客户端接入：支持 Codex、Claude Code、OpenCode、Pi、Hermes 和 WorkBuddy。

效果展示

文献目录

[Obsidian 文献目录]

Literature Index

[Literature Index]

多篇文献形成的可追溯 Wiki

展开效果图 [可追溯 Wiki 综合页面]

安装

3.0.2 已正式发布，要求 Python 3.10+。以下公开安装命令现已可用。

uv（推荐）

powershell
uv tool install "zotero-obsidian-mcp==3.0.2"obsidian-vault-mcp --help

无需持久安装：

powershell
uvx --from "zotero-obsidian-mcp==3.0.2" obsidian-vault-mcp doctor --vault-path "<VAULT_PATH>"

pipx / pip

powershell
pipx install "zotero-obsidian-mcp==3.0.2"# 或python -m pip install "zotero-obsidian-mcp==3.0.2"

MCP Registry

text
io.github.luffysolution-svg/obsidian-vault-mcp

等价的 stdio 配置：

json
{  "mcpServers": {    "obsidian-literature": {      "command": "uvx",      "args": [        "--from",        "zotero-obsidian-mcp==3.0.2",        "obsidian-vault-mcp",        "serve",        "--transport",        "stdio"      ],      "env": {        "OBSIDIAN_VAULT_PATH": "<VAULT_PATH>"      }    }  }}

首次配置

目标目录必须是已由 Obsidian 打开过的 Vault，并包含 .obsidian/。

powershell
obsidian-vault-mcp config init --vault-path "<VAULT_PATH>" --dry-runobsidian-vault-mcp config init --vault-path "<VAULT_PATH>"obsidian-vault-mcp config validate --vault-path "<VAULT_PATH>"obsidian-vault-mcp doctor --vault-path "<VAULT_PATH>"obsidian-vault-mcp call literature_version --json '{}'

启动 Zotero Desktop 并启用本地 API：

powershell
obsidian-vault-mcp call zotero_search_items --json '{"query":"photocatalysis"}'obsidian-vault-mcp import item ABCD1234 --vault-path "<VAULT_PATH>" --dry-runobsidian-vault-mcp import item ABCD1234 --vault-path "<VAULT_PATH>"

链接附件配置：

json
{  "zotero": {    "linkedAttachmentBaseDir": "<ZOTERO_LINKED_ATTACHMENT_BASE_DIR>"  }}

MinerU 解析：

powershell
obsidian-vault-mcp mineru parse ABCD1234 --vault-path "<VAULT_PATH>" --dry-runobsidian-vault-mcp mineru parse ABCD1234 --vault-path "<VAULT_PATH>"

规范产物：

text
Literature/attachment/MinerU/ABCD1234.mdLiterature/attachment/MinerU/image/ABCD1234/ABCD1234-fig01.png

Agent 与插件安装

powershell
obsidian-vault-mcp agent install codex --dry-runobsidian-vault-mcp agent install codex

客户端名称可替换为 claude、opencode、pi、hermes 或 workbuddy。

客户端安装内容
Codex原生 marketplace 插件、MCP 和 7 Skills
Claude Code原生 marketplace 插件、MCP 和 7 Skills
OpenCode项目本地 MCP 和 7 Skills
Pi薄 TypeScript Extension
HermesMCP 配置
WorkBuddyMCP 配置

GitHub Release 中的离线插件包：

text
obsidian-vault-mcp-3.0.2-plugins.zip

Skills

Skill工作流
paper-qa单篇快速问答，默认不写入 Vault
full-read单篇完整精读并保存 full_read
passage-qa定位具体段落、方法、数据或结论
figure-qa解读图、表、Scheme 和方程
compare-papers对用户选定论文建立可比性矩阵
literature-review对文献池进行主题化综述
concept-learning跨文献建立概念模型

正式工具面

分组数量
版本、系统与配置5
Zotero6
导入与同步4
MinerU3
导航与校验3
Analysis5
Wiki3
事务2
合计31

发布一致性

3.0.2 必须同时出现在 Python 包、运行时 __version__、MCP Registry server.json、Codex/Claude 插件清单、Pi 包、Git Tag v3.0.2、GitHub Release 和 PyPI 中。Release workflow 会校验版本、Tag 和产物身份，构建 wheel、sdist、插件 ZIP，执行测试与 handshake，并生成 SHA256SUMS。

安全边界

  • 所有写操作先 dry-run，再提交并保存 transactionId。
  • 不要提交 Vault 绝对路径、Zotero 数据目录、MinerU token 或其他凭据。
  • MinerU 可能把 PDF 发送到外部服务，使用前确认授权和组织政策。
  • 推荐本地 stdio；SSE/HTTP 必须放在可信认证边界之后。
  • 事务备份不替代独立的 Vault 备份。

贡献者

感谢 方珸 / Lym Fang (@LimFang) 提出 Zotero 链接附件兼容方案。完整记录见 CONTRIBUTORS.md。

來源：README.md，提交 7161bdf

工具

0
SourceWeft 尚未在沙箱中啟動過該軟體包，因此其工具未知。

版本歷史

1
  1. v3.0.2最新Sep 16, 2026

評分

已滿足適用檢查項的 50%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分

    請保持端點能夠回應 MCP 握手；SourceWeft 每 30 天探測一次。

  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具15 分

    請讓伺服器在無憑證時回應 tools/list，或發布可在沙箱中無憑證啟動的軟體包。

  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分