academic-workflow-mcp
Allows creating, updating, and managing structured literature notes in an Obsidian vault, including syncing highlights and updating note status.
Allows fetching paper metadata, full text, and annotations from Zotero, attaching notes with backlinks, updating tags, and listing papers by collection or tag.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@academic-workflow-mcp Fetch paper with citekey wang2024deep and create an Obsidian note"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Step | Tool | Description |
0. Import |
| Batch-import PDFs into Zotero with title extraction and deduplication |
0. Dedupe |
| Scan for duplicate Zotero items by identical DOI or similar title |
1. Fetch |
| Pull metadata + full text + annotations from Zotero in one call |
2. Write |
| Create a structured Obsidian note with YAML frontmatter |
3. Link |
| Add a short summary note under the Zotero item with a back-link |
4. Sync |
| Propagate PDF highlights (by color category) into the Obsidian note |
5. Archive |
| After human review — update status in Obsidian + tags in Zotero |
+ |
| List papers by tag/collection, optionally cross-checking Obsidian |
+ |
| Read an existing Obsidian literature note |
+ |
| 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
Option A — pip from GitHub (recommended)
pip install git+https://github.com/wuruiqi/zo-bridge.gitThis 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-bridgeOption 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 |
| — | ✅ | Key from the Local REST API plugin settings |
|
| Obsidian REST API base URL | |
| — | Vault name for | |
|
| Vault folder for literature notes | |
|
| Zotero local connector URL | |
| — | for writes | Zotero Web API key |
| — | for writes | Numeric library ID (shown at zotero.org/settings/keys) |
|
|
| |
| — | for PDF import | Path to your Zotero data directory (e.g. |
🔌 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=Falseis a dry run — review the report before passingTrue.
🛠 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
relatedfrontmatter field.Default
LITERATURE_FOLDERchanged from10-Literature→0-Literature.
v0.2.0
New:
workflow_import_pdfs— batch PDF import with real-title extraction, filename/content mismatch detection, and smart deduplicationNew:
workflow_find_duplicates— scan Zotero for duplicate items by DOI or similar titleNew:
workflow_sync_check— bidirectional deletion sync: clean orphan Obsidian notes when Zotero items are trashed, and vice versaConfig: added
ZOTERO_DATA_DIRenv 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 toolsworkflow_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:
Extracts the real title from the PDF (metadata field, then largest-font first-page text) instead of using the filename stem.
Detects title mismatches between the filename and the PDF content — useful for catching mislabeled downloads (e.g. wrong paper saved under a different name).
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.
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:
"trash_to_obs" — Zotero items in trash → find orphaned Obsidian notes. When auto_apply=True, deletes those Obsidian notes.
"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.
"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
Scored across 10 tools
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.
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.
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.
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
Related MCP Connectors
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn 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.920MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language interaction with Zotero libraries, allowing users to search, retrieve, and update papers and metadata via AI assistants like Claude and Gemini.1GPL 2.0
- AlicenseNot gradedqualityDmaintenanceConnects 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
- AlicenseAqualityBmaintenanceEnables AI assistants to search, access, and interact with your Zotero research library, including semantic search, metadata retrieval, PDF annotations, and library management.41MIT