{
  "markdown": "<!-- mcp-name: io.github.luffysolution-svg/obsidian-vault-mcp -->\n\n# Obsidian Vault MCP\n\n面向科研文献工作流的本地 MCP 服务：以 Zotero 管理来源，以 MinerU 提取全文，以 Obsidian 沉淀文献、Wiki 与结构化 Analysis，并通过 Skills 让 AI Agent 按可追溯流程工作。\n\n[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)\n\n## 架构\n\n```text\n用户自然语言任务\n        ↓\n7 个科研 Skills：识别意图、规划步骤、约束证据与输出\n        ↓\n31 个 MCP Tools：版本契约、查询、导入、解析、检索、校验与事务写入\n        ↓\nZotero Desktop ── PDF ── MinerU ── Obsidian Vault\n                                      ├─ Literature 主笔记\n                                      ├─ PDF 与全文 Markdown\n                                      ├─ Index / Literature.base\n                                      ├─ Wiki\n                                      └─ 五类 Analysis / Analysis.base\n```\n\n项目不绑定大模型供应商。MCP Tools 负责确定性的本地数据操作，Skills 负责把工具编排成可复用的科研工作流。\n\n## 核心功能\n\n- **稳定文献身份**：以 Zotero 父条目 `zoteroKey` 作为主键。\n- **Zotero 导入与同步**：支持单篇、Collection、notes、annotations、BibTeX、存储附件和链接附件。\n- **MinerU 全文解析**：将 PDF 规范化为 Markdown，每篇文献使用独立图片目录和相对链接。\n- **Obsidian 文献库**：自动维护 `Literature/index.md`、`Literature/Literature.base`、主笔记、PDF、全文和 Wiki。\n- **结构化研究层**：支持 `full_read`、`literature_review`、`passage_qa`、`figure_qa`、`concept` 五类 Analysis。\n- **统一数据库视图**：`Literature/Analysis/Analysis.base` 提供 9 个视图。\n- **科研 Skills**：内置 `paper-qa`、`full-read`、`passage-qa`、`figure-qa`、`compare-papers`、`literature-review`、`concept-learning`。\n- **安全写入**：支持 dry-run、staging、锁、备份、原子替换、事务预览和回滚。\n- **版本可验证**：`literature_version` 返回当前版本、31 个工具、7 个 Skills 和五类 Analysis。\n- **多客户端接入**：支持 Codex、Claude Code、OpenCode、Pi、Hermes 和 WorkBuddy。\n\n## 效果展示\n\n### 文献目录\n\n<img src=\"https://raw.githubusercontent.com/luffysolution-svg/obsidian-vault-mcp/main/docs/assets/screenshots/v2/vault-structure.png\" alt=\"Obsidian 文献目录\" width=\"320\">\n\n### Literature Index\n\n<img src=\"https://raw.githubusercontent.com/luffysolution-svg/obsidian-vault-mcp/main/docs/assets/screenshots/v2/literature-index.png\" alt=\"Literature Index\" width=\"760\">\n\n### 多篇文献形成的可追溯 Wiki\n\n<details>\n<summary>展开效果图</summary>\n\n<img src=\"https://raw.githubusercontent.com/luffysolution-svg/obsidian-vault-mcp/main/docs/assets/screenshots/v2/wiki-synthesis.png\" alt=\"可追溯 Wiki 综合页面\" width=\"780\">\n\n</details>\n\n## 安装\n\n`3.0.2` 已正式发布，要求 Python 3.10+。以下公开安装命令现已可用。\n\n### uv（推荐）\n\n```powershell\nuv tool install \"zotero-obsidian-mcp==3.0.2\"\nobsidian-vault-mcp --help\n```\n\n无需持久安装：\n\n```powershell\nuvx --from \"zotero-obsidian-mcp==3.0.2\" obsidian-vault-mcp doctor --vault-path \"<VAULT_PATH>\"\n```\n\n### pipx / pip\n\n```powershell\npipx install \"zotero-obsidian-mcp==3.0.2\"\n# 或\npython -m pip install \"zotero-obsidian-mcp==3.0.2\"\n```\n\n### MCP Registry\n\n```text\nio.github.luffysolution-svg/obsidian-vault-mcp\n```\n\n等价的 stdio 配置：\n\n```json\n{\n  \"mcpServers\": {\n    \"obsidian-literature\": {\n      \"command\": \"uvx\",\n      \"args\": [\n        \"--from\",\n        \"zotero-obsidian-mcp==3.0.2\",\n        \"obsidian-vault-mcp\",\n        \"serve\",\n        \"--transport\",\n        \"stdio\"\n      ],\n      \"env\": {\n        \"OBSIDIAN_VAULT_PATH\": \"<VAULT_PATH>\"\n      }\n    }\n  }\n}\n```\n\n## 首次配置\n\n目标目录必须是已由 Obsidian 打开过的 Vault，并包含 `.obsidian/`。\n\n```powershell\nobsidian-vault-mcp config init --vault-path \"<VAULT_PATH>\" --dry-run\nobsidian-vault-mcp config init --vault-path \"<VAULT_PATH>\"\nobsidian-vault-mcp config validate --vault-path \"<VAULT_PATH>\"\nobsidian-vault-mcp doctor --vault-path \"<VAULT_PATH>\"\nobsidian-vault-mcp call literature_version --json '{}'\n```\n\n启动 Zotero Desktop 并启用本地 API：\n\n```powershell\nobsidian-vault-mcp call zotero_search_items --json '{\"query\":\"photocatalysis\"}'\nobsidian-vault-mcp import item ABCD1234 --vault-path \"<VAULT_PATH>\" --dry-run\nobsidian-vault-mcp import item ABCD1234 --vault-path \"<VAULT_PATH>\"\n```\n\n链接附件配置：\n\n```json\n{\n  \"zotero\": {\n    \"linkedAttachmentBaseDir\": \"<ZOTERO_LINKED_ATTACHMENT_BASE_DIR>\"\n  }\n}\n```\n\nMinerU 解析：\n\n```powershell\nobsidian-vault-mcp mineru parse ABCD1234 --vault-path \"<VAULT_PATH>\" --dry-run\nobsidian-vault-mcp mineru parse ABCD1234 --vault-path \"<VAULT_PATH>\"\n```\n\n规范产物：\n\n```text\nLiterature/attachment/MinerU/ABCD1234.md\nLiterature/attachment/MinerU/image/ABCD1234/ABCD1234-fig01.png\n```\n\n## Agent 与插件安装\n\n```powershell\nobsidian-vault-mcp agent install codex --dry-run\nobsidian-vault-mcp agent install codex\n```\n\n客户端名称可替换为 `claude`、`opencode`、`pi`、`hermes` 或 `workbuddy`。\n\n| 客户端 | 安装内容 |\n|---|---|\n| Codex | 原生 marketplace 插件、MCP 和 7 Skills |\n| Claude Code | 原生 marketplace 插件、MCP 和 7 Skills |\n| OpenCode | 项目本地 MCP 和 7 Skills |\n| Pi | 薄 TypeScript Extension |\n| Hermes | MCP 配置 |\n| WorkBuddy | MCP 配置 |\n\nGitHub Release 中的离线插件包：\n\n```text\nobsidian-vault-mcp-3.0.2-plugins.zip\n```\n\n## Skills\n\n| Skill | 工作流 |\n|---|---|\n| `paper-qa` | 单篇快速问答，默认不写入 Vault |\n| `full-read` | 单篇完整精读并保存 `full_read` |\n| `passage-qa` | 定位具体段落、方法、数据或结论 |\n| `figure-qa` | 解读图、表、Scheme 和方程 |\n| `compare-papers` | 对用户选定论文建立可比性矩阵 |\n| `literature-review` | 对文献池进行主题化综述 |\n| `concept-learning` | 跨文献建立概念模型 |\n\n## 正式工具面\n\n| 分组 | 数量 |\n|---|---:|\n| 版本、系统与配置 | 5 |\n| Zotero | 6 |\n| 导入与同步 | 4 |\n| MinerU | 3 |\n| 导航与校验 | 3 |\n| Analysis | 5 |\n| Wiki | 3 |\n| 事务 | 2 |\n| **合计** | **31** |\n\n## 发布一致性\n\n`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`。\n\n## 安全边界\n\n- 所有写操作先 dry-run，再提交并保存 `transactionId`。\n- 不要提交 Vault 绝对路径、Zotero 数据目录、MinerU token 或其他凭据。\n- MinerU 可能把 PDF 发送到外部服务，使用前确认授权和组织政策。\n- 推荐本地 `stdio`；SSE/HTTP 必须放在可信认证边界之后。\n- 事务备份不替代独立的 Vault 备份。\n\n## 贡献者\n\n感谢 [方珸 / Lym Fang (@LimFang)](https://github.com/LimFang) 提出 Zotero 链接附件兼容方案。完整记录见 [CONTRIBUTORS.md](https://github.com/luffysolution-svg/obsidian-vault-mcp/blob/main/CONTRIBUTORS.md)。\n",
  "bytes": 6040,
  "sha": "f7c7b3036a8c66305a9aaf150e98c97605690ff05faf972cd5730c8a3216544d",
  "repo_slug": "luffysolution-svg/obsidian-vault-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_luffysolution_svg_obsidian_vau_05550674/readme"
}