zo-bridge

zo-bridge is an MCP server that connects Zotero and Obsidian into one streamlined, AI-assisted workflow — compatible with Claude Code, Codex, OpenClaw, Cursor, and any other MCP client.

中文简介： zo-bridge 将 Zotero（文献管理）与 Obsidian（知识库）连接为统一的 AI 辅助工作流。支持批量导入 PDF、自动提取标题、查重检测、双向删除同步，以及结构化笔记的生成与归档。生成的笔记是项目无关的中立知识资产，不绑定任何具体课题。

✨ What it does

The AI handles analysis and writing; the MCP server handles plumbing (API calls, file I/O, format consistency).

Related MCP server: research-hub

🛠 Prerequisites

🚀 Installation

Option A — pip from GitHub (recommended)

pip install git+https://github.com/wuruiqi/zo-bridge.git

This installs an zo-bridge command that starts the stdio MCP server.

Option B — uvx (no install)

uvx --from git+https://github.com/wuruiqi/zo-bridge.git zo-bridge

Option C — clone and run

git clone https://github.com/wuruiqi/zo-bridge.git
cd zo-bridge
pip install -e .
cp .env.example .env    # fill in your keys

⚙️ Configuration

Copy .env.example to .env and fill in your values:

🔌 Register with your MCP client

Claude Code / Claude Desktop

{
  "mcpServers": {
    "zo-bridge": {
      "command": "zo-bridge",
      "env": {
        "OBSIDIAN_API_KEY": "your_key",
        "OBSIDIAN_VAULT_NAME": "Research",
        "ZOTERO_API_KEY": "your_key",
        "ZOTERO_LIBRARY_ID": "12345678",
        "ZOTERO_DATA_DIR": "C:\\Users\\you\\Zotero"
      }
    }
  }
}

Codex / OpenClaw / Cursor (any stdio MCP client)

{
  "mcpServers": {
    "zo-bridge": {
      "type": "stdio",
      "command": "zo-bridge"
    }
  }
}

Or with uvx (no pre-install):

{
  "mcpServers": {
    "zo-bridge": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/wuruiqi/zo-bridge.git",
        "zo-bridge"
      ]
    }
  }
}

📖 Typical workflow

# 0. Batch-import a folder of PDFs you just downloaded:
"Import all PDFs in D:/papers/slam/ into Zotero collection '1_SLAM'"

# The AI calls:
workflow_import_pdfs(["D:/papers/slam/wang2024.pdf", ...], collection="1_SLAM")
  → imports PDFs, extracts real titles, warns on filename/content mismatches,
    skips files already in Zotero

# 0b. Check for duplicates after import:
"Find duplicate papers in my SLAM collection"

workflow_find_duplicates(collections=["1_SLAM"])
  → returns groups of items sharing a DOI or a highly similar title

# 1. Ask your AI assistant:
"Read and annotate the paper with citekey wang2024deep"

# The AI will call:
workflow_get_paper("wang2024deep")
  → returns metadata, full text, annotations

# Then generate the note content and call:
workflow_write_note(citekey, metadata, sections)
  → creates 0-Literature/wang2024deep.md in Obsidian

workflow_attach_zotero_note(item_key, citekey, summary)
  → adds a summary note under the Zotero item

# 2. You review the note in Obsidian, then tell the AI:
"wang2024deep confirmed, mark as reviewed"

# The AI calls:
workflow_confirm_review("wang2024deep", item_key)
  → Obsidian: status → reviewed
  → Zotero: #在读 → #已精读

# 3. Later, after highlighting the PDF in Zotero:
"Sync my highlights for wang2024deep"

workflow_sync_highlights("wang2024deep", item_key)
  → appends color-categorized highlights to the note

# 4. Periodically clean up after deleting papers in Zotero:
"Check if any Obsidian notes need to be cleaned up after my recent Zotero deletions"

workflow_sync_check(direction="both")
  → dry-run report of orphan notes and ghost items

workflow_sync_check(direction="both", auto_apply=True)
  → actually deletes orphan Obsidian notes and trashes ghost Zotero items

🗂 Note structure

Literature notes follow a bilingual heading convention so the LLM can fill sections regardless of the user's language:

---
citekey: "wang2024deep"
title: "..."
authors: [Wang, X., Li, Y.]
year: 2024
journal: "IEEE TPAMI"
doi: "10.1109/..."
zotero: "zotero://select/library/items/XXXXXXXX"
tags: [literature]
rating: ⭐⭐⭐
status: pending-review
related: []
---

## One-line Summary / 一句话总结
## Research Question & Motivation / 研究问题与动机
## Methods / 方法
## Key Results / 主要结果
## Contributions / 创新点
## Limitations & Open Questions / 局限与可质疑之处
## Highlights from Paper / 关键引文摘录

Notes are project-neutral by design: there is no "relevance to my project" section — a paper is a reusable knowledge asset, and which project it serves is decided later via tags and back-links. Related papers are linked through the related frontmatter field (["[[other2024key]]"]).

Highlights are grouped by annotation color:

🧰 MCP tools reference

workflow_import_pdfs(pdf_paths, collection="", item_type="preprint")

Batch-import PDF files into Zotero with automatic title extraction and smart deduplication.

• Extracts the real title from PDF metadata or largest-font first-page text (not just the filename).

• Detects title mismatches between the filename and PDF content — useful for catching mislabeled downloads.

• Smart dedup: if an identical file already has a PDF in Zotero → skip; if a metadata-only entry exists with no PDF → attach PDF to it rather than creating a duplicate.

• Copies the PDF into <zotero_data_dir>/storage/ so Zotero can open it immediately.

Returns imported, skipped, failed, and warnings (title mismatches) lists.

workflow_find_duplicates(collections=[], title_threshold=0.85)

Scan Zotero for duplicate items grouped by identical DOI or highly similar title.

• collections: collection names to scan; leave empty to scan the entire library.

• title_threshold: word-overlap ratio (default 0.85). Lower to catch more near-duplicates.

Returns grouped duplicate sets with a suggested_keep item key for each group.

workflow_get_paper(identifier)

Retrieve metadata, full text, and annotations from Zotero by citekey, item key, DOI, or title.

workflow_write_note(citekey, metadata, sections, overwrite=False)

Write a structured literature note to 0-Literature/<citekey>.md with status: pending-review.

workflow_attach_zotero_note(item_key, citekey, summary, rating, cite_in)

Create a short child note under the Zotero item with an obsidian:// back-link.

workflow_sync_highlights(citekey, item_key)

Pull PDF annotations from Zotero and update the highlights section of the Obsidian note.

workflow_confirm_review(citekey, item_key, tag_remove, tag_add)

Mark a note as reviewed: status → reviewed in Obsidian, tag update in Zotero.

workflow_list_papers(tag, collection, limit, check_notes)

List Zotero papers filtered by tag or collection, with optional Obsidian note status.

workflow_get_note(citekey)

Read the current content of a literature note from Obsidian.

workflow_sync_check(direction="both", auto_apply=False)

Bidirectional deletion sync between Zotero and Obsidian.

• "trash_to_obs": finds Obsidian notes whose Zotero item is now in the trash.

• "obs_to_zotero": finds orphan Obsidian notes (Zotero item deleted) and Zotero items whose linked Obsidian note was removed.

• "both": runs both directions.

• Default auto_apply=False is a dry run — review the report before passing True.

🛠 Development

git clone https://github.com/wuruiqi/zo-bridge.git
cd zo-bridge
pip install -e ".[dev]"
cp .env.example .env
python -m pytest tests/ -m "not integration"

Integration tests (-m integration) require Zotero and Obsidian to be running.

📋 Changelog

v0.3.0

• Renamed: project is now zo-bridge (package, command, and MCP server name all changed from academic-workflow-mcp → zo-bridge). Update your client config's command and server key.

• Notes are now project-neutral: the literature note template drops the "Relevance to My Research" and "Further Reading" sections — a note is a reusable knowledge asset; project relevance is tracked via tags/back-links, not baked into the note. Related papers go in the related frontmatter field.

• Default LITERATURE_FOLDER changed from 10-Literature → 0-Literature.

v0.2.0

• New: workflow_import_pdfs — batch PDF import with real-title extraction, filename/content mismatch detection, and smart deduplication

• New: workflow_find_duplicates — scan Zotero for duplicate items by DOI or similar title

• New: workflow_sync_check — bidirectional deletion sync: clean orphan Obsidian notes when Zotero items are trashed, and vice versa

• Config: added ZOTERO_DATA_DIR env variable for PDF storage during import

v0.1.0

• Initial release: workflow_get_paper, workflow_write_note, workflow_attach_zotero_note, workflow_sync_highlights, workflow_confirm_review, workflow_list_papers, workflow_get_note

License

MIT © wuruiqi