Skip to content
Back to search

obsidian-vault-mcp

obsidian-vault-mcp

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/luffysolution-svg--obsidian-vault-mcp/badge.svg)](/listings/luffysolution-svg--obsidian-vault-mcp)

HTML

<a href="/listings/luffysolution-svg--obsidian-vault-mcp"><img src="/api/listings/luffysolution-svg--obsidian-vault-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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

uv(推荐)

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

无需持久安装:

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

pipx / pip

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

MCP Registry

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

等价的 stdio 配置:

{
  "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>"
      }
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 222 lines · 1 finding marked

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <!-- mcp-name: io.github.luffysolution-svg/obsidian-vault-mcp -->
  2. # Obsidian Vault MCP
  3. 面向科研文献工作流的本地 MCP 服务:以 Zotero 管理来源,以 MinerU 提取全文,以 Obsidian 沉淀文献、Wiki 与结构化 Analysis,并通过 Skills 让 AI Agent 按可追溯流程工作。
  4. [English](https://github.com/luffysolution-svg/obsidian-vault-mcp/blob/main/README.en.md) · [完整安装教程](https://github.com/luffysolution-svg/obsidian-vault-mcp/blob/main/docs/index.md) · [开发文档](https://github.com/luffysolution-svg/obsidian-vault-mcp/blob/main/DEVELOPMENT.md) · [更新日志](https://github.com/luffysolution-svg/obsidian-vault-mcp/blob/main/CHANGELOG.md) · [贡献者](https://github.com/luffysolution-svg/obsidian-vault-mcp/blob/main/CONTRIBUTORS.md)
  5. ## 架构
  6. ```text
  7. 用户自然语言任务
  8. ↓
  9. 7 个科研 Skills:识别意图、规划步骤、约束证据与输出
  10. ↓
  11. 31 个 MCP Tools:版本契约、查询、导入、解析、检索、校验与事务写入
  12. ↓
  13. Zotero Desktop ── PDF ── MinerU ── Obsidian Vault
  14. ├─ Literature 主笔记
  15. ├─ PDF 与全文 Markdown
  16. ├─ Index / Literature.base
  17. ├─ Wiki
  18. └─ 五类 Analysis / Analysis.base
  19. ```
  20. 项目不绑定大模型供应商。MCP Tools 负责确定性的本地数据操作,Skills 负责把工具编排成可复用的科研工作流。
  21. ## 核心功能
  22. - **稳定文献身份**:以 Zotero 父条目 `zoteroKey` 作为主键。
  23. - **Zotero 导入与同步**:支持单篇、Collection、notes、annotations、BibTeX、存储附件和链接附件。
  24. - **MinerU 全文解析**:将 PDF 规范化为 Markdown,每篇文献使用独立图片目录和相对链接。
  25. - **Obsidian 文献库**:自动维护 `Literature/index.md`、`Literature/Literature.base`、主笔记、PDF、全文和 Wiki。
  26. - **结构化研究层**:支持 `full_read`、`literature_review`、`passage_qa`、`figure_qa`、`concept` 五类 Analysis。
  27. - **统一数据库视图**:`Literature/Analysis/Analysis.base` 提供 9 个视图。
  28. - **科研 Skills**:内置 `paper-qa`、`full-read`、`passage-qa`、`figure-qa`、`compare-papers`、`literature-review`、`concept-learning`。
  29. - **安全写入**:支持 dry-run、staging、锁、备份、原子替换、事务预览和回滚。
  30. - **版本可验证**:`literature_version` 返回当前版本、31 个工具、7 个 Skills 和五类 Analysis。
  31. - **多客户端接入**:支持 Codex、Claude Code、OpenCode、Pi、Hermes 和 WorkBuddy。
  32. ## 效果展示
  33. ### 文献目录
  34. <img src="https://raw.githubusercontent.com/luffysolution-svg/obsidian-vault-mcp/main/docs/assets/screenshots/v2/vault-structure.png" alt="Obsidian 文献目录" width="320">
  35. ### Literature Index
  36. <img src="https://raw.githubusercontent.com/luffysolution-svg/obsidian-vault-mcp/main/docs/assets/screenshots/v2/literature-index.png" alt="Literature Index" width="760">
  37. ### 多篇文献形成的可追溯 Wiki
  38. <details>
  39. <summary>展开效果图</summary>
  40. <img src="https://raw.githubusercontent.com/luffysolution-svg/obsidian-vault-mcp/main/docs/assets/screenshots/v2/wiki-synthesis.png" alt="可追溯 Wiki 综合页面" width="780">
  41. </details>
  42. ## 安装
  43. `3.0.2` 已正式发布,要求 Python 3.10+。以下公开安装命令现已可用。
  44. ### uv(推荐)
  45. ```powershell
  46. uv tool install "zotero-obsidian-mcp==3.0.2"
  47. obsidian-vault-mcp --help
  48. ```
  49. 无需持久安装:
  50. ```powershell
  51. uvx --from "zotero-obsidian-mcp==3.0.2" obsidian-vault-mcp doctor --vault-path "<VAULT_PATH>"
  52. ```
  53. ### pipx / pip
  54. ```powershell
  55. pipx install "zotero-obsidian-mcp==3.0.2"
  56. # 或
  57. python -m pip install "zotero-obsidian-mcp==3.0.2"
  58. ```
  59. ### MCP Registry
  60. ```text
  61. io.github.luffysolution-svg/obsidian-vault-mcp
  62. ```
  63. 等价的 stdio 配置:
  64. ```json
  65. {
  66. "mcpServers": {
  67. "obsidian-literature": {
  68. "command": "uvx",
  69. "args": [
  70. "--from",
  71. "zotero-obsidian-mcp==3.0.2",
  72. "obsidian-vault-mcp",
  73. "serve",
  74. "--transport",
  75. "stdio"
  76. ],
  77. "env": {
  78. "OBSIDIAN_VAULT_PATH": "<VAULT_PATH>"
  79. }
  80. }
  81. }
  82. }
  83. ```
  84. ## 首次配置
  85. 目标目录必须是已由 Obsidian 打开过的 Vault,并包含 `.obsidian/`。
  86. ```powershell
  87. obsidian-vault-mcp config init --vault-path "<VAULT_PATH>" --dry-run
  88. obsidian-vault-mcp config init --vault-path "<VAULT_PATH>"
  89. obsidian-vault-mcp config validate --vault-path "<VAULT_PATH>"
  90. obsidian-vault-mcp doctor --vault-path "<VAULT_PATH>"
  91. obsidian-vault-mcp call literature_version --json '{}'
  92. ```
  93. 启动 Zotero Desktop 并启用本地 API:
  94. ```powershell
  95. obsidian-vault-mcp call zotero_search_items --json '{"query":"photocatalysis"}'
  96. obsidian-vault-mcp import item ABCD1234 --vault-path "<VAULT_PATH>" --dry-run
  97. obsidian-vault-mcp import item ABCD1234 --vault-path "<VAULT_PATH>"
  98. ```
  99. 链接附件配置:
  100. ```json
  101. {
  102. "zotero": {
  103. "linkedAttachmentBaseDir": "<ZOTERO_LINKED_ATTACHMENT_BASE_DIR>"
  104. }
  105. }
  106. ```
  107. MinerU 解析:
  108. ```powershell
  109. obsidian-vault-mcp mineru parse ABCD1234 --vault-path "<VAULT_PATH>" --dry-run
  110. obsidian-vault-mcp mineru parse ABCD1234 --vault-path "<VAULT_PATH>"
  111. ```
  112. 规范产物:
  113. ```text
  114. Literature/attachment/MinerU/ABCD1234.md
  115. Literature/attachment/MinerU/image/ABCD1234/ABCD1234-fig01.png
    • Dismissed after review: Contains a long base64-looking blob — not necessarily malicious, but worth inspecting what it decodes to
    • Line 155 on GitHub
  116. ```
  117. ## Agent 与插件安装
  118. ```powershell
  119. obsidian-vault-mcp agent install codex --dry-run
  120. obsidian-vault-mcp agent install codex
  121. ```
  122. 客户端名称可替换为 `claude`、`opencode`、`pi`、`hermes` 或 `workbuddy`。
  123. | 客户端 | 安装内容 |
  124. |---|---|
  125. | Codex | 原生 marketplace 插件、MCP 和 7 Skills |
  126. | Claude Code | 原生 marketplace 插件、MCP 和 7 Skills |
  127. | OpenCode | 项目本地 MCP 和 7 Skills |
  128. | Pi | 薄 TypeScript Extension |
  129. | Hermes | MCP 配置 |
  130. | WorkBuddy | MCP 配置 |
  131. GitHub Release 中的离线插件包:
  132. ```text
  133. obsidian-vault-mcp-3.0.2-plugins.zip
  134. ```
  135. ## Skills
  136. | Skill | 工作流 |
  137. |---|---|
  138. | `paper-qa` | 单篇快速问答,默认不写入 Vault |
  139. | `full-read` | 单篇完整精读并保存 `full_read` |
  140. | `passage-qa` | 定位具体段落、方法、数据或结论 |
  141. | `figure-qa` | 解读图、表、Scheme 和方程 |
  142. | `compare-papers` | 对用户选定论文建立可比性矩阵 |
  143. | `literature-review` | 对文献池进行主题化综述 |
  144. | `concept-learning` | 跨文献建立概念模型 |
  145. ## 正式工具面
  146. | 分组 | 数量 |
  147. |---|---:|
  148. | 版本、系统与配置 | 5 |
  149. | Zotero | 6 |
  150. | 导入与同步 | 4 |
  151. | MinerU | 3 |
  152. | 导航与校验 | 3 |
  153. | Analysis | 5 |
  154. | Wiki | 3 |
  155. | 事务 | 2 |
  156. | **合计** | **31** |
  157. ## 发布一致性
  158. `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`。
  159. ## 安全边界
  160. - 所有写操作先 dry-run,再提交并保存 `transactionId`。
  161. - 不要提交 Vault 绝对路径、Zotero 数据目录、MinerU token 或其他凭据。
  162. - MinerU 可能把 PDF 发送到外部服务,使用前确认授权和组织政策。
  163. - 推荐本地 `stdio`;SSE/HTTP 必须放在可信认证边界之后。
  164. - 事务备份不替代独立的 Vault 备份。
  165. ## 贡献者
  166. 感谢 [方珸 / Lym Fang (@LimFang)](https://github.com/LimFang) 提出 Zotero 链接附件兼容方案。完整记录见 [CONTRIBUTORS.md](https://github.com/luffysolution-svg/obsidian-vault-mcp/blob/main/CONTRIBUTORS.md)。

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.