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 "Install 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 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、自动提取标题、查重检测、双向删除同步，以及结构化笔记的生成与归档。生成的笔记是项目无关的中立知识资产，不绑定任何具体课题。
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: research-hub
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 |
pip install git+https://github.com/wuruiqi/zo-bridge.gitThis installs an zo-bridge command that starts the stdio MCP server.
uvx --from git+https://github.com/wuruiqi/zo-bridge.git zo-bridgegit clone https://github.com/wuruiqi/zo-bridge.git
cd zo-bridge
pip install -e .
cp .env.example .env # fill in your keysCopy .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. |
{
"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"
}
}
}
}{
"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"
]
}
}
}# 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 itemsLiterature 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 |
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.
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.
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.
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
Initial release: workflow_get_paper, workflow_write_note, workflow_attach_zotero_note, workflow_sync_highlights, workflow_confirm_review, workflow_list_papers, workflow_get_note
MIT © wuruiqi
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}
| Name | Required | Description | Default |
|---|---|---|---|
| rating | No | ⭐⭐⭐ | |
| cite_in | No | ||
| citekey | Yes | ||
| summary | Yes | ||
| item_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses the character limit (≤200 chars), the linking behavior to Obsidian, and the return format. However, it does not discuss error handling, side effects, or rate limits. It adequately covers the main behavioral traits but lacks depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured with distinct sections: one-sentence purpose, requirements, parameter list with helpful notes, and return format. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the 5 parameters, no output schema, and no annotations, the description is largely complete. It explains all parameters, return format, and prerequisites. Minor gaps include not clarifying what a 'child note' is in Zotero or constraints on the Obsidian link, but overall it provides sufficient context for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must fully explain parameters. It does so effectively: item_key is '8-char Zotero internal key', citekey is 'Better BibTeX citekey for obsidian link', summary is 'one-sentence, ≤150 chars', rating defaults to '⭐⭐⭐', and cite_in is 'grant/paper section'. This adds substantial meaning beyond the schema's titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Create a short child note (≤200 chars) under the Zotero item that links back to the Obsidian deep note.' This is a specific verb+resource with scope (short child note, linking to Obsidian), and it distinguishes the tool from siblings like workflow_get_note and workflow_write_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description mentions required environment variables (ZOTERO_API_KEY, ZOTERO_LIBRARY_ID) and lists arguments, which provides some usage context. However, it does not explicitly state when to use this tool versus alternatives (e.g., workflow_write_note for longer notes) or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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": {...}}
| Name | Required | Description | Default |
|---|---|---|---|
| citekey | Yes | ||
| tag_add | No | 已精读 | |
| item_key | Yes | ||
| tag_remove | No | 在读 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses the write operations (updating Obsidian and Zotero) and the return structure, compensating for absent annotations. Lacks details on error handling or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise and well-structured with an Args section, but slightly verbose with default values repeated in both the description and schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers the action, all parameters with defaults, and return format exhaustively, making it fully self-contained for an agent to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description adds full meaning for all four parameters, including types and defaults, citing specific examples like 'Better BibTeX citekey' and tag defaults with translations.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it marks a literature note as reviewed by updating Obsidian frontmatter and Zotero tags, using specific verbs and resources. This distinguishes it from sibling workflow tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states to call only after human review and approval, providing clear when-to-use guidance. However, it does not mention alternatives or when not to use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, }
| Name | Required | Description | Default |
|---|---|---|---|
| collections | No | ||
| title_threshold | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes that it scans entire library if collections empty, uses title threshold, and returns grouped duplicates with suggested keep. No annotations provided, but description covers key behavioral aspects for a scan tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded purpose, efficient use of words. Includes detailed return structure despite no output schema. No redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Provides return value structure, input semantics, and usage context. Sibling tool names indicate this is the only duplicate finder, so completeness is high.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage, but description fully explains both parameters: collections (names or empty for all) and title_threshold (word-overlap ratio, default 0.85, effect of lower values). Adds significant meaning beyond schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it scans Zotero for duplicate items by DOI or similar title. Distinct from sibling tools which deal with notes, papers, and imports.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises running before a reading session or after batch import to prevent duplicate annotation work. Does not explicitly mention when not to use, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}
| Name | Required | Description | Default |
|---|---|---|---|
| citekey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses read-only nature and return schema but lacks details on auth, rate limits, or error handling. Since no annotations exist, additional behavioral context would be beneficial.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded, every sentence adds value. Args and returns clearly formatted with no extraneous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers purpose, usage, parameter, and return format adequately for a simple read tool. Minor missing details like behavior on missing notes are implied by the return structure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description fully explains the sole parameter 'citekey' as a Better BibTeX citekey equivalent to filename without .md, which is critical given 0% schema description coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly describes reading a literature note from Obsidian vault with specific verb and resource. Could explicitly differentiate from siblings like workflow_write_note, but the context is sufficient.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides use cases (review, check status, decide overwrite/patch) but does not explicitly state when not to use or name alternatives among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 }
| Name | Required | Description | Default |
|---|---|---|---|
| identifier | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full burden. It details the return structure including a 'found' bool and possible empty fields ('fulltext may be empty'). No contradictions, but could mention error handling or performance traits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose, then usage, parameters, and return format. Every sentence earns its place; no redundancy. Ideal balance of detail and brevity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one parameter, no output schema, but rich return format described with sample JSON. Covers all needed info for analysis: metadata, fulltext, annotations, existence flags. Adequate for an LLM to use effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single parameter 'identifier' lacks schema description (0% coverage), but the Args section adds rich meaning: examples (Zotero key, citekey, DOI, title keywords) far exceed schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'Retrieve' and resource 'everything needed to analyze a paper' including metadata, full text, and PDF annotations. Explicitly positions as first step before generating a literature note, distinguishing it from sibling tools like workflow_get_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit context: 'Use this as the first step before generating a literature note.' While it does not list alternatives or when not to use, the context is clear and sufficient for guiding the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 /storage// 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) }
| Name | Required | Description | Default |
|---|---|---|---|
| item_type | No | preprint | |
| pdf_paths | Yes | ||
| collection | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. It explains the title extraction method (metadata then largest-font text), deduplication logic (skip identical file, attach to existing metadata-only entry), and storage copying behavior. It does not cover error handling or rate limits, but the provided details are substantial and clear.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with numbered improvements, Args, and Returns sections. It front-loads the main purpose and key features. While slightly lengthy, every part contributes value and the organization helps readability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 0% schema coverage and no output schema, the description provides a detailed return structure and explains all parameters. It covers the core behavior (title extraction, deduplication, storage) and return value fields. Missing details like error handling for invalid paths are minor; overall, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does so by listing parameters in the Args section with context: pdf_paths (absolute paths), collection (exact case-sensitive, empty for root), and item_type (default 'preprint', with example values). This adds meaning beyond the schema's type and default fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it imports PDFs into Zotero with automatic title extraction and smart deduplication. It distinguishes itself from a related tool (zotero_add_from_file) by listing specific improvements, and sibling tool names indicate different workflows, making its unique purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear context for when to use the tool (importing PDFs) and mentions improvements over zotero_add_from_file, but it does not explicitly guide the agent on when not to use it or how it compares to sibling tools like workflow_get_paper or workflow_find_duplicates. The usage guidelines are implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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?}, ...]}
| Name | Required | Description | Default |
|---|---|---|---|
| tag | No | ||
| limit | No | ||
| collection | No | ||
| check_notes | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Without annotations, the description carries full weight and delivers: it explains the optional cross-check, the performance impact of check_notes ('Slower when True'), and the precedence rule ('collection takes precedence over tag'). It also discloses the default limit and the return format including note_status. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a concise opening sentence, a usage line, and clearly labeled Args/Returns sections. Every sentence adds value; no redundancy or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (interaction with Zotero and Obsidian, 4 parameters, no output schema), the description covers the return format and parameter behavior well. However, it does not mention prerequisites (e.g., API keys) or error handling, which could be useful for completeness. Still, it is largely adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. It does so thoroughly: each parameter is explained with examples (e.g., '待读' or '#待读'), default values, precedence rules, and the effect of check_notes. This adds substantial meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a clear verb-resource pair: 'List papers from Zotero'. It specifies filtering by tag or collection, and an optional cross-check with Obsidian. This distinguishes it from sibling tools like workflow_get_paper (single paper retrieval) and workflow_sync_highlights (highlight syncing).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states usage: 'Use this to build a reading queue or to identify papers that still need to be processed.' This provides clear context. It does not, however, mention when not to use it or compare directly with siblings, but the guidance is sufficient.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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, }
| Name | Required | Description | Default |
|---|---|---|---|
| direction | No | both | |
| auto_apply | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility. It details the destructive actions (deleting Obsidian notes, trashing Zotero items) when auto_apply=True, and the safe dry-run mode. It does not mention authorization or rate limits, but the behavioral effects are sufficiently covered.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-organized with headings, bullet points, and a clear argument specification. Each sentence is informative, and the structure aids readability. It is appropriately sized for the tool's complexity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of a bidirectional sync check with multiple sub-checks and side effects, and no output schema, the description provides a comprehensive explanation. It details all three direction modes, dry-run vs. auto_apply behavior, and the return structure in a pseudo-JSON format, making it complete for an agent to use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully carries the burden. It clarifies the allowed values for 'direction' (trash_to_obs, obs_to_zotero, both) and explains the effect of 'auto_apply' (report only vs. actually delete/trash), adding critical meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Bidirectional sync check between Zotero and Obsidian' and enumerates three specific direction modes. It distinguishes itself from sibling tools like workflow_attach_zotero_note and workflow_sync_highlights by focusing on sync consistency rather than note creation or highlight synchronization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use each direction (trash_to_obs, obs_to_zotero, both) and explicitly warns about the dry_run default and the need to review output before setting auto_apply=True. However, it does not explicitly contrast with sibling tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}
| Name | Required | Description | Default |
|---|---|---|---|
| citekey | Yes | ||
| item_key | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full responsibility. It discloses key behaviors: it replaces existing highlight content, leaves metadata untouched, and returns a JSON with success, count, and message. This level of detail adequately informs an agent of side effects and safety profile.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured. It opens with a clear one-sentence purpose, followed by usage guidance, then a structured Args section with brief but sufficient definitions, and finally a Return type description. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool has 2 simple parameters, no output schema, and no annotations, the description covers the core behavior, parameter semantics, and return format. It could be slightly more explicit about prerequisites (e.g., Zotero and Obsidian connection) and the fact that this is a write operation, but overall it is largely complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates. It defines 'citekey' as 'Better BibTeX citekey (used to locate the Obsidian note)' and 'item_key' as 'Zotero internal item key (needed to fetch annotations).' This adds crucial meaning beyond the parameter names alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's action: 'Pull PDF annotations from Zotero and update the 'Highlights from Paper' section of the corresponding Obsidian literature note.' It uses a specific verb ('pull', 'update') and resource ('PDF annotations', 'Obsidian literature note'), and this purpose is distinct from sibling tools like workflow_sync_check or workflow_write_note.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit usage context: 'Run this any time after you have highlighted the PDF in Zotero.' It also clarifies behavioral constraints: 'Existing highlight content is replaced; metadata sections are untouched.' However, it does not explicitly state when not to use the tool or mention alternatives, though the specific workflow context makes the guidance clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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}
| Name | Required | Description | Default |
|---|---|---|---|
| citekey | Yes | ||
| metadata | Yes | ||
| sections | Yes | ||
| overwrite | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description fully carries the burden. Discloses file location, YAML frontmatter, status 'pending-review', placeholder handling for omitted sections, overwrite semantics, and return value structure. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with separate paragraphs for overall behavior, then Args and Returns. Concise without unnecessary fluff. Could be slightly tighter but is effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description includes return type and structure. Covers all parameters, behavior, workflow with sibling tool reference. Nested objects are sufficiently detailed. No gaps for a write tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% but description thoroughly explains each parameter: citekey as Better BibTeX key (filename), metadata with expected keys (title, authors, year, journal, doi, zotero_link), sections with recognized keys and placeholder behavior, overwrite with default false. Adds meaning beyond schema structure.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the verb 'write' and the resource 'structured literature note', with specific location '10-Literature/<citekey>.md' and mention of YAML frontmatter and section headings. Distinguishes from sibling tools like workflow_get_note and workflow_attach_zotero_note by focusing on note creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit guidance: note is created with status 'pending-review' and instructs to call workflow_confirm_review after human checks. Also explains overwrite behavior to avoid clobbering. Lacks explicit 'when not to use' but provides clear workflow context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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…
Academic literature search, retrieval, and private library management on top of OpenAlex.
Federated search of books and papers, BibTeX/RIS citations, open-access retrieval and reading.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/wuruiqi/zo-bridge'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
