Skip to main content
Glama
academic-workflow-mcp

academic-workflow-mcp

by wuruiqi

zo-bridge

License: MIT Python 3.10+

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

Step

Tool

Description

0. Import

workflow_import_pdfs

Batch-import PDFs into Zotero with title extraction and deduplication

0. Dedupe

workflow_find_duplicates

Scan for duplicate Zotero items by identical DOI or similar title

1. Fetch

workflow_get_paper

Pull metadata + full text + annotations from Zotero in one call

2. Write

workflow_write_note

Create a structured Obsidian note with YAML frontmatter

3. Link

workflow_attach_zotero_note

Add a short summary note under the Zotero item with a back-link

4. Sync

workflow_sync_highlights

Propagate PDF highlights (by color category) into the Obsidian note

5. Archive

workflow_confirm_review

After human review — update status in Obsidian + tags in Zotero

+

workflow_list_papers

List papers by tag/collection, optionally cross-checking Obsidian

+

workflow_get_note

Read an existing Obsidian literature note

+

workflow_sync_check

Bidirectional deletion sync — clean up orphan notes and trashed items

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


Related MCP server: Stratosphere MCP Zotero

🛠 Prerequisites

Requirement

Notes

Python 3.10+

Required by the MCP SDK

Zotero 7+ desktop app

Must be running; local API on port 23119

Better BibTeX plugin for Zotero

Generates stable citekeys used as universal IDs

Obsidian desktop app

Must be running

Local REST API Obsidian plugin

Exposes vault API on port 27123

Zotero Web API key

For write operations (tags, child notes). Get one at zotero.org/settings/keys


🚀 Installation

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:

Variable

Default

Required

Description

OBSIDIAN_API_KEY

—

✅

Key from the Local REST API plugin settings

OBSIDIAN_URL

http://127.0.0.1:27123

Obsidian REST API base URL

OBSIDIAN_VAULT_NAME

—

Vault name for obsidian:// deep-links

LITERATURE_FOLDER

0-Literature

Vault folder for literature notes

ZOTERO_LOCAL_URL

http://127.0.0.1:23119

Zotero local connector URL

ZOTERO_API_KEY

—

for writes

Zotero Web API key

ZOTERO_LIBRARY_ID

—

for writes

Numeric library ID (shown at zotero.org/settings/keys)

ZOTERO_LIBRARY_TYPE

user

user or group

ZOTERO_DATA_DIR

—

for PDF import

Path to your Zotero data directory (e.g. C:\Users\you\Zotero)


🔌 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:

Color

Category

🟡 Yellow

Key Point

🔴 Red

Critical / Question

🟢 Green

Method / Technique

🔵 Blue

Data / Result

🟣 Purple

Background


🧰 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

Available Tools

10 tools
workflow_attach_zotero_noteA

Create a short child note (≤200 chars) under the Zotero item that links back to the Obsidian deep note.

Requires ZOTERO_API_KEY and ZOTERO_LIBRARY_ID to be set.

Args: item_key: Zotero internal item key (8-char, e.g. "7BDH2DPA"). citekey: Better BibTeX citekey (used to build the obsidian:// link). summary: One-sentence summary of the paper (≤150 chars recommended). rating: Star rating, default "⭐⭐⭐". cite_in: Grant/paper section where this can be cited (e.g. "Methods 2.1").

Returns: {"success": bool, "key": str, "message": str}

Inputs: citekey (required), summary (required), item_key (required), rating, +1 more.

workflow_confirm_reviewA

Mark a literature note as reviewed: update the Obsidian frontmatter status to 'reviewed' and update the Zotero item tags.

Call this only after the human has reviewed and approved the note.

Args: citekey: Better BibTeX citekey. item_key: Zotero internal item key. tag_remove: Zotero tag to remove (default "在读" / "reading"). tag_add: Zotero tag to add (default "已精读" / "reviewed").

Returns: {"success": bool, "obsidian": {...}, "zotero": {...}}

Inputs: citekey (required), item_key (required), tag_add, tag_remove.

workflow_find_duplicatesA

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

Run this before starting a reading session or after a batch import to catch entries that were added twice, preventing duplicate annotation work.

Args: collections: Collection names to scan (e.g. ["1_SLAM与退化导航", "2_3DGS与三维重建"]). Leave empty to scan the entire library. title_threshold: Word-overlap ratio for title similarity (default 0.85). 0.85 catches near-identical titles; lower values cast a wider net.

Returns: { "duplicate_groups": [ { "reason": "Same DOI" | "Similar title", "doi": str, "suggested_keep": str, # item key recommended to keep "items": [ {key, title, year, authors, journal, doi, zotero_link}, ... ], } ], "total_duplicates": int, # total number of items that are duplicates "group_count": int, "tip": str, }

Inputs: collections, title_threshold.

workflow_get_noteA

Read the current content of a literature note from the Obsidian vault.

Useful for reviewing what has already been written, checking the status, or deciding whether to overwrite vs. patch a note.

Args: citekey: Better BibTeX citekey (= filename without .md).

Returns: {"exists": bool, "path": str, "content": str, "status": str | None}

Inputs: citekey (required).

workflow_get_paperA

Retrieve everything needed to analyze a paper: metadata, full text, and PDF annotations from Zotero — all in one call.

Use this as the first step before generating a literature note. The returned data gives the LLM sufficient context to fill every section of the note template.

Args: identifier: Zotero item key (e.g. "7BDH2DPA"), Better BibTeX citekey (e.g. "wang2024deep"), DOI, or title keywords.

Returns: { "found": bool, "item": {key, citekey, title, authors, year, journal, doi, abstract, tags, zotero_link}, "fulltext": str, # indexed PDF text (may be empty) "annotations": [ # PDF highlights & notes {type, text, comment, color_label, page}, ... ], "has_fulltext": bool, "has_annotations": bool, "note_path": str, # expected Obsidian path for the note "note_exists": bool, # whether a note already exists }

Inputs: identifier (required).

workflow_import_pdfsA

Import PDF files into Zotero with automatic title extraction and smart deduplication.

Improvements over zotero-mcp's zotero_add_from_file:

  1. Extracts the real title from the PDF (metadata field, then largest-font first-page text) instead of using the filename stem.

  2. Detects title mismatches between the filename and the PDF content — useful for catching mislabeled downloads (e.g. wrong paper saved under a different name).

  3. Smart deduplication:

    • If an identical file already has a PDF in Zotero → skip.

    • If a matching metadata-only entry exists (no PDF yet) → attach PDF to it rather than creating a duplicate parent item.

  4. Copies the PDF into <zotero_data_dir>/storage/<attachment_key>/ so Zotero can open it immediately without any manual "Locate File" step.

Args: pdf_paths: List of absolute file paths to PDFs. collection: Zotero collection name (exact, case-sensitive). Leave empty for library root. item_type: Zotero item type for new parent items. Default "preprint". Other values: "journalArticle", "conferencePaper".

Returns: { "imported": [ {item_key, attachment_key, title, title_source, filename_stem, title_mismatch, attached_to_existing, storage_copied, path} ], "skipped": [ {path, item_key, title, reason} ], "failed": [ {path, error} ], "warnings": [ {path, filename_stem, extracted_title, title_source, message} ], # title mismatches needing user review "count": int, # newly imported (excludes skipped) }

Inputs: pdf_paths (required), item_type, collection.

workflow_list_papersA

List papers from Zotero filtered by tag or collection, with optional cross-check against the Obsidian vault to see which already have notes.

Use this to build a reading queue or to identify papers that still need to be processed.

Args: tag: Zotero tag to filter by (e.g. "待读" or "#待读"). If empty, returns all items (up to limit). collection: Zotero collection name. Takes precedence over tag if both given. limit: Maximum number of items to return (default 30). check_notes: If True, adds "note_status" to each item showing the Obsidian note status (None = no note, "pending-review", "reviewed", etc.). Slower when True.

Returns: {"count": int, "items": [{citekey, title, authors, year, tags, date_added, note_status?}, ...]}

Inputs: tag, limit, collection, check_notes.

workflow_sync_checkA

Bidirectional sync check between Zotero and Obsidian.

Three checks are performed depending on direction:

  1. "trash_to_obs" — Zotero items in trash → find orphaned Obsidian notes. When auto_apply=True, deletes those Obsidian notes.

  2. "obs_to_zotero" — Obsidian literature notes → find those whose Zotero item is gone (was deleted). When auto_apply=True, deletes orphan notes from Obsidian. Also finds Zotero items that had Obsidian notes created via workflow_attach_zotero_note but the note has since been deleted; when auto_apply=True, moves those Zotero items to trash.

  3. "both" — runs both directions above.

Default is dry_run mode (auto_apply=False) — reports findings without making any changes. Review the output before setting auto_apply=True.

Args: direction: "trash_to_obs" | "obs_to_zotero" | "both" auto_apply: False (default) = report only. True = actually delete/trash.

Returns: { "trash_to_obs": { "zotero_trash_items": [...], "orphan_notes_found": [...], # notes to delete "deleted_notes": [...], # notes actually deleted (auto_apply=True) }, "obs_to_zotero": { "obsidian_notes_total": int, "orphan_notes": [...], # notes with no Zotero item → delete note "deleted_orphan_notes": [...], "items_note_deleted": [...], # Zotero items whose notes were removed "trashed_items": [...], # items actually trashed (auto_apply=True) }, "auto_apply": bool, "summary": str, }

Inputs: direction, auto_apply.

workflow_sync_highlightsA

Pull PDF annotations from Zotero and update the 'Highlights from Paper' section of the corresponding Obsidian literature note.

Run this any time after you have highlighted the PDF in Zotero. Existing highlight content is replaced; metadata sections are untouched.

Args: citekey: Better BibTeX citekey (used to locate the Obsidian note). item_key: Zotero internal item key (needed to fetch annotations).

Returns: {"success": bool, "count": int, "message": str}

Inputs: citekey (required), item_key (required).

workflow_write_noteA

Write a structured literature note directly to the Obsidian vault at 10-Literature/.md with proper YAML frontmatter and section headings.

The note is created with status "pending-review". Call workflow_confirm_review after the human has checked the note.

Args: citekey: Better BibTeX citation key (used as filename, e.g. "wang2024deep"). metadata: Dict with keys — title, authors (list[str]), year, journal, doi, zotero_link. Use the 'item' dict from workflow_get_paper. sections: Dict mapping section keys to content strings. Recognized keys: one_line_summary, research_question, methods, results, contributions, limitations, relevance, highlights, further_reading Any key may be omitted; the heading is still written with a placeholder. overwrite: If False (default) and a note already exists, returns an error so you do not silently clobber a reviewed note.

Returns: {"success": bool, "path": str, "obsidian_link": str, "message": str}

Inputs: citekey (required), metadata (required), sections (required), overwrite.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool targets a distinct step in the academic workflow, from importing and retrieving papers to writing notes, syncing highlights, and managing duplicates. There is no functional overlap; the descriptions clearly delineate their purposes.

    Naming Consistency5/5

    All tool names follow the 'workflow_verb_noun' pattern consistently, using snake_case throughout. The verbs (get, write, list, attach, confirm, etc.) are descriptive and follow a predictable structure.

    Tool Count5/5

    With 10 tools, the server is well-scoped for its domain of academic literature management. Each tool covers a necessary aspect of the workflow, and the count is neither too few nor excessive.

    Completeness4/5

    The tools cover the full lifecycle from import to review, including duplicate detection and syncing. Minor gaps exist, such as the lack of a dedicated tool to update note content in-place (though write_note with overwrite partially addresses this). Overall, an agent can accomplish most tasks without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      An AI-powered research assistant that integrates with Zotero to read academic papers, create intelligent annotations, and generate structured notes. It enables users to highlight findings, explain formulas, and write comprehensive summaries directly within their Zotero library through natural language commands.
      9
      20
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language interaction with Zotero libraries, allowing users to search, retrieve, and update papers and metadata via AI assistants like Claude and Gemini.
      1
      GPL 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects your Zotero research library with AI assistants (Claude, ChatGPT, etc.) via the Model Context Protocol, enabling paper review, summaries, annotations, and semantic search both locally and through the web API.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables AI assistants to search, access, and interact with your Zotero research library, including semantic search, metadata retrieval, PDF annotations, and library management.
      41
      MIT