Obsidian Vault

Obsidian Vault

工具列表（17个核心工具）

默认只提供 17 个专注于 Zotero→MinerU→Obsidian 文献管道的 MCP 工具：

类别	工具
Pipeline	obsidian_pipeline_doctor、obsidian_pipeline_config、obsidian_pipeline_migrate_layout
文献导入	obsidian_pipeline_ingest_item、obsidian_pipeline_ingest_collection
MinerU	obsidian_pipeline_parse_with_mineru、obsidian_pipeline_rename_mineru_images
Zotero	obsidian_zotero_ping、obsidian_zotero_search_items、obsidian_zotero_list_collections、obsidian_zotero_get_item、obsidian_zotero_get_children、obsidian_zotero_list_pdf_attachments
Vault 基础	obsidian_read_file、obsidian_write_file、obsidian_search、obsidian_update_properties

Skills（技能）

图谱分析、Wiki 维护、Canvas/Bases/Dataview 视图、Obsidian CLI 控制等高级工作流已转为 Skills，通过 Claude Code 或 Codex 调用：

Skill	功能
obsidian-vault	图谱、lint、wiki、schema、批量编辑、文件管理
obsidian-cli	Obsidian 桌面 CLI 控制
obsidian-views	Canvas、Bases、Dataview
obsidian-graph	引用网络、社区检测、连通性分析
obsidian-mineru	MinerU 直接解析、批量处理
obsidian-zotero	Zotero 搜索与文献导入

Vault-local pipeline config lives in .obsidian-vault-pipeline.json:

{
  "literatureFolder": "literature",
  "zoteroAttachmentsFolder": "attachments/zotero",
  "mineruAttachmentsFolder": "attachments/mineru",
  "noteFilenamePattern": "{firstAuthor} {year} - {shortTitle}",
  "pdfFilenamePattern": "{shortTitle}",
  "mineruMarkdownName": "paper.md",
  "mineruImagesIndexName": "images-index.md"
}

面向 Codex、Claude Code 和 OpenCode 的本地 MCP 插件，将本地 Obsidian vault 维护成可持续增长的双链知识库。

English README | 安装配置教程 | 技术文档 | 文档站

快速开始

方式一：PyPI 安装（推荐）

pip install zotero-obsidian-mcp
obsidian-vault-mcp --doctor --doctor-format text --vault /path/to/your-vault

方式二：源码安装（开发者 / 跟进最新提交）

git clone https://github.com/luffysolution-svg/obsidian-vault-mcp.git
cd obsidian-vault-mcp
pip install -e .
obsidian-vault-mcp --doctor --doctor-format text --vault /path/to/your-vault

将本目录注册为 Codex 本地插件，或将 MCP server 添加到 Claude Code 或 OpenCode，然后重启或重新加载 MCP 客户端。个人 vault 路径、Zotero 存储路径、API token 和私有笔记内容只保存在本地配置中，不要提交到仓库。

功能概览

• Vault 文件搜索、读取、写入和 YAML property 更新。
• Zotero Desktop 本地 API 集成：搜索、元数据获取、子条目、PDF 附件。
• 从 Zotero 条目一步导入文献笔记，复制 PDF 到 vault，保留 zotero:// 链接。
• 可选调用 MinerU Open API CLI 直接解析 PDF/文档后导入，支持批量处理。
• MinerU 解析图片按正文图注自动重命名为语义文件名，保留中文字符。
• 导入时自动解析 Zotero 集合名称，空字段不写入 frontmatter。
• --doctor 就绪检查脚本（Zotero、MinerU、vault 配置）。
• 随插件发布一组标准 skills，帮助 Codex/Claude Code 自动命中合适的工作流。pip install 安装后 skills 位于 Python 包目录内；clone 源码安装后位于仓库根目录 skills/。

配置

在本地 MCP 配置中设置 OBSIDIAN_VAULT_PATH，或在每次工具调用时传入 vault_path。.mcp.json 默认使用 auto，会通过本地 Obsidian CLI 获取当前活动 vault，CLI 不可用时回退到进程工作目录。

{
  "OBSIDIAN_VAULT_PATH": "auto",
  "OBSIDIAN_CLI_COMMAND": "obsidian"
}

CLI 封装需要 Obsidian 1.12.7 或更高版本，且 obsidian 命令在 PATH 中。

Zotero 工具需要 Zotero Desktop 本地 API 运行在 http://127.0.0.1:23119/api，可通过 ZOTERO_LOCAL_API 覆盖。

MinerU 支持是可选的。已有 MinerU Markdown 可直接导入，无需安装 MinerU。如需直接解析文档，安装 mineru-open-api 并使用 obsidian_mineru_* 工具。flash-extract 无需 token；精确 extract 可能需要 MinerU token。本插件不会自动安装 MinerU CLI、MinerU MCP、Zotero Desktop 或 Obsidian CLI。

与 Zotero 联动的推荐三步工作流：

1. obsidian_pipeline_ingest_item（传入 zotero_key）→ 将文献导入 literature/，生成完整 YAML、笔记和批注。
2. obsidian_pipeline_parse_with_mineru（传入 zotero_key）→ 解析 PDF，在 attachments/mineru/ 生成全文笔记，同时向文献 note 的 YAML 追加 MinerU 跳转链接。
3. 文献 note 的正文和其他 YAML 字段完全不变，仅新增一个可点击的 MinerU 全文链接。

MinerU 提取会调用多个 MinerU/OpenXLab 端点。使用 VPN、代理或 fake-IP DNS 时，请确保以下域名可直连：

• mineru.net
• mineru.oss-cn-shanghai.aliyuncs.com
• cdn-mineru.openxlab.org.cn
• *.openxlab.org.cn

常见失败场景：解析任务和 OSS 上传成功，但从 cdn-mineru.openxlab.org.cn 下载 full.md 时出现 TLS/EOF 错误。遇到此问题请先检查代理/DNS 规则。 NO_PROXY 在显式 HTTP 代理场景下可能有帮助，但在全局代理、TUN 或 fake-IP 路由模式下经常不会生效。这种情况下通常需要直接在代理客户端里配置直连或 DNS bypass 规则。

默认要求路径解析到包含 .obsidian 的文件夹。只有在明确使用普通 Markdown 文件夹时才设置 OBSIDIAN_ALLOW_NON_VAULT=true。

Vault 内默认配置

可在 vault 根目录的 .obsidian-vault-mcp.json 或 .obsidian/obsidian-vault-mcp.json 中保存可复用的默认值。工具参数显式传入时优先级更高。

{
  "literatureFolder": "01-literature",
  "mineruSourceFolder": "02-sources/mineru",
  "pdfSourceFolder": "02-sources/pdf",
  "entitiesFolder": "entities",
  "conceptsFolder": "concepts",
  "zoteroAttachmentsFolder": "assets/zotero",
  "zoteroAttachmentNameStrategy": "zotero_key",
  "indexPath": "index.md",
  "logPath": "log.md",
  "templateFolder": "Templates",
  "defaultTemplate": "Literature"
}