Skip to content
Back to search

ZotLink

Production‑ready MCP server for Zotero to save open preprints (arXiv, CVF, bio/med/chemRxiv) with rich metadata and smart PDF attachments — with upcoming support for publisher databases (Nature, Science, IEEE Xplore, Springer).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/tonybotni--zotlink/badge.svg)](/listings/tonybotni--zotlink)

HTML

<a href="/listings/tonybotni--zotlink"><img src="/api/listings/tonybotni--zotlink/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1️⃣ Install

pip install zotlink
python -m playwright install chromium

*Requires Python 3.10+. Includes full browser support for all preprint servers by default!*

2️⃣ One-Command Configuration ✨

Use `zotlink init` to automatically generate MCP configuration:

# Auto-detect Zotero path
zotlink init

# Or specify path manually
zotlink init /Users/yourname/Zotero

**The command outputs ready-to-use configuration JSON**, for example:

{
  "mcpServers": {
    "zotlink": {
      "command": "/opt/homebrew/.../zotlink",
      "args": [],
      "env": {
        "ZOTLINK_ZOTERO_ROOT": "/Users/yourname/Zotero"
      }
    }
  }
}

3️⃣ Add to Claude Configuration

Copy the generated configuration to your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Linux**: `~/.config/claude/claude_desktop_config.json` - **Windows**: `~/AppData/Roaming/Claude/claude_desktop_config.json`

Restart Claude Desktop and you're ready to go!

---

🛠️ Development Installation

git clone https://github.com/your-org/ZotLink.git
cd ZotLink
pip install -e .
python -m playwright install chromium

MCP Configuration Details

If you need manual configuration (without using `zotlink init`), see examples below:

<details> <summary><b>📝 Manual Configuration Examples (click to expand)</b></summary>

**Recommended configuration** (simple - just specify Zotero directory):

{
  "mcpServers": {
    "zotlink": {
      "command": "/path/to/zotlink",
      "args": [],
      "env": {
        "ZOTLINK_ZOTERO_ROOT": "/Users/yourname/Zotero"
      }
    }
  }
}

**Advanced configuration** (specify paths separately):

{
  "mcpServers": {
    "zotlink": {
      "command": "/path/to/zotlink",
      "args": [],
      "env": {
        "ZOTLINK_ZOTERO_DB": "/Users/yourname/Zotero/zotero.sqlite",
        "ZOTLINK_ZOTERO_DIR": "/Users/yourname/Zotero/storage"
      }
    }
  }
}

**Minimal config** (auto-detect Zotero paths):

{
  "mcpServers": {
    "zotlink": { "command": "zotlink", "args": [] }
  }
}

**Note**: Using `env` variables follows MCP standard and works with all MCP clients (Claude Desktop, Cherry Studio, etc.).

</details>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 296 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <div align="center">
  2. <img src="https://pic-1313147768.cos.ap-chengdu.myqcloud.com/ZotLink/logo.png" alt="ZotLink Logo" width="150" height="150">
  3. # ZotLink
  4. MCP Server for Zotero Connector
  5. [![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
  6. [![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
  7. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  8. [![Platforms](https://img.shields.io/badge/platforms-macOS%20|%20Windows%20|%20Linux-lightgrey)]()
  9. **🌍 Language / 语言选择:**
  10. [🇺🇸 English](README.md) | [🇨🇳 中文](README_zh.md)
  11. </div>
  12. ## 🔗 ZotLink
  13. A lightweight, production-ready MCP server that brings open scholarly sources into Zotero with one command.
  14. ❤️ Like ZotLink? Give it a star 🌟 to support the development!
  15. ## ✨ Core Features
  16. - 🌐 **Open Preprint Coverage**: arXiv, CVF (OpenAccess), bioRxiv, medRxiv, chemRxiv
  17. - 🧠 **Rich Metadata Extraction**: title, authors, abstract, DOI, subjects, comments
  18. - 📄 **Smart PDF Attachment**: auto-attach when available; validated link fallback
  19. - 📚 **One-Click Collection Save**: list + save (updateSession, treeViewID: C{id})
  20. - 🧭 **Adaptive Browser Strategy**: Playwright for tough sites; HTTP for the rest
  21. - 💻 **Client Compatibility**: Works with Claude Desktop and Cherry Studio
  22. - 🧩 **Deep MCP Interoperability**: Integrates with literature-related MCPs such as [arxiv-mcp-server](https://github.com/blazickjp/arxiv-mcp-server) and [Zotero MCP](https://github.com/54yyyu/zotero-mcp)
  23. - 📝 **Unified Logging**: `~/.zotlink/zotlink.log`
  24. ---
  25. ### 🎥 Demo Video
  26. <div align="center">
  27. [![Watch the video](https://pic-1313147768.cos.ap-chengdu.myqcloud.com/ZotLink/bili_face.png)](https://www.bilibili.com/video/BV1o6xazvEfH/)
  28. > **Click the image above to watch a 1-minute demo video on Bilibili.**
  29. </div>
  30. ---
  31. ## 🚀 Quick Start
  32. ### 1️⃣ Install
  33. ```bash
  34. pip install zotlink
  35. python -m playwright install chromium
  36. ```
  37. *Requires Python 3.10+. Includes full browser support for all preprint servers by default!*
  38. ### 2️⃣ One-Command Configuration ✨
  39. Use `zotlink init` to automatically generate MCP configuration:
  40. ```bash
  41. # Auto-detect Zotero path
  42. zotlink init
  43. # Or specify path manually
  44. zotlink init /Users/yourname/Zotero
  45. ```
  46. **The command outputs ready-to-use configuration JSON**, for example:
  47. ```json
  48. {
  49. "mcpServers": {
  50. "zotlink": {
  51. "command": "/opt/homebrew/.../zotlink",
  52. "args": [],
  53. "env": {
  54. "ZOTLINK_ZOTERO_ROOT": "/Users/yourname/Zotero"
  55. }
  56. }
  57. }
  58. }
  59. ```
  60. ### 3️⃣ Add to Claude Configuration
  61. Copy the generated configuration to your Claude Desktop config file:
  62. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  63. - **Linux**: `~/.config/claude/claude_desktop_config.json`
  64. - **Windows**: `~/AppData/Roaming/Claude/claude_desktop_config.json`
  65. Restart Claude Desktop and you're ready to go!
  66. ---
  67. ### 🛠️ Development Installation
  68. ```bash
  69. git clone https://github.com/your-org/ZotLink.git
  70. cd ZotLink
  71. pip install -e .
  72. python -m playwright install chromium
  73. ```
  74. ### MCP Configuration Details
  75. If you need manual configuration (without using `zotlink init`), see examples below:
  76. <details>
  77. <summary><b>📝 Manual Configuration Examples (click to expand)</b></summary>
  78. **Recommended configuration** (simple - just specify Zotero directory):
  79. ```json
  80. {
  81. "mcpServers": {
  82. "zotlink": {
  83. "command": "/path/to/zotlink",
  84. "args": [],
  85. "env": {
  86. "ZOTLINK_ZOTERO_ROOT": "/Users/yourname/Zotero"
  87. }
  88. }
  89. }
  90. }
  91. ```
  92. **Advanced configuration** (specify paths separately):
  93. ```json
  94. {
  95. "mcpServers": {
  96. "zotlink": {
  97. "command": "/path/to/zotlink",
  98. "args": [],
  99. "env": {
  100. "ZOTLINK_ZOTERO_DB": "/Users/yourname/Zotero/zotero.sqlite",
  101. "ZOTLINK_ZOTERO_DIR": "/Users/yourname/Zotero/storage"
  102. }
  103. }
  104. }
  105. }
  106. ```
  107. **Minimal config** (auto-detect Zotero paths):
  108. ```json
  109. {
  110. "mcpServers": {
  111. "zotlink": { "command": "zotlink", "args": [] }
  112. }
  113. }
  114. ```
  115. **Note**: Using `env` variables follows MCP standard and works with all MCP clients (Claude Desktop, Cherry Studio, etc.).
  116. </details>
  117. ## 🧰 Available Tools
  118. - `check_zotero_status`: Check if Zotero is running and reachable
  119. - `get_zotero_collections`: List collections (tree view) from the local DB
  120. - `save_paper_to_zotero`: Save a paper by URL (arXiv/CVF/rxiv), attach PDF/metadata
  121. - `extract_arxiv_metadata`: Extract full arXiv metadata (title/authors/subjects/DOI/comment)
  122. - Cookie helpers (stubs prepared) for auth-required sources
  123. ## 📁 Logging
  124. Logs are written to `~/.zotlink/zotlink.log`.
  125. ## 🌐 Browser Mode
  126. Browser-driven extraction is included by default! All preprint servers (bioRxiv, medRxiv, chemRxiv) work automatically.
  127. The server switches to browser strategy automatically when needed (falls back to HTTP mode on Windows).
  128. **Linux may require additional system dependencies**:
  129. ```bash
  130. sudo apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libgbm1 libasound2
  131. ```
  132. ### Advanced: Custom Zotero Paths
  133. <details>
  134. <summary><b>🔧 Environment Variable Configuration (click to expand)</b></summary>
  135. **Recommended - Single directory**:
  136. ```bash
  137. # macOS/Linux
  138. export ZOTLINK_ZOTERO_ROOT=/Users/yourname/Zotero
  139. # Windows PowerShell
  140. $env:ZOTLINK_ZOTERO_ROOT='C:\Users\YourName\Zotero'
  141. ```
  142. **Advanced - Separate paths**:
  143. ```bash
  144. # macOS/Linux
  145. export ZOTLINK_ZOTERO_DB=/Users/yourname/Zotero/zotero.sqlite
  146. export ZOTLINK_ZOTERO_DIR=/Users/yourname/Zotero/storage
  147. # Windows PowerShell
  148. $env:ZOTLINK_ZOTERO_DB='C:\Users\YourName\Zotero\zotero.sqlite'
  149. $env:ZOTLINK_ZOTERO_DIR='C:\Users\YourName\Zotero\storage'
  150. ```
  151. **Local config file** `~/.zotlink/config.json`:
  152. ```json
  153. {
  154. "zotero": {
  155. "database_path": "/Users/yourname/Zotero/zotero.sqlite",
  156. "storage_dir": "/Users/yourname/Zotero/storage"
  157. }
  158. }
  159. ```
  160. **Configuration precedence**: ENV vars > MCP env config > local config file > auto-detection
  161. </details>
  162. ## 🧩 Supported Sources (Open)
  163. - **arXiv** (preprint)
  164. - **CVF (OpenAccess)** (CVPR/ICCV/WACV)
  165. - **bioRxiv** / **medRxiv** / **chemRxiv** (preprint servers)
  166. Auth-required sources (e.g., Nature) are planned via bookmark-based cookie sync.
  167. ## 🧰 Troubleshooting
  168. - Zotero not detected: ensure Zotero Desktop is running (port 23119)
  169. - No PDF attached: some pages only expose links; the server falls back to link attachments
  170. - Browser mode errors: verify Playwright is installed and Chromium is available
  171. - Install error: ensure Python 3.10+ is installed
  172. ## 🧪 Development
  173. ```bash
  174. pip install -e .
  175. python -m playwright install chromium
  176. zotlink # or: python run_server.py
  177. ```
  178. See `docs/DEVELOPMENT.md` for code structure, adding new extractors, and release tips.
  179. ## 🗺️ Roadmap (To‑Do)
  180. - Sources
  181. - [x] arXiv
  182. - [x] CVF (OpenAccess)
  183. - [x] bioRxiv
  184. - [x] medRxiv
  185. - [x] chemRxiv
  186. - [ ] Nature (cookies)
  187. - [ ] Science (cookies)
  188. - [ ] IEEE Xplore (cookies)
  189. - [ ] Springer (cookies)
  190. - [ ] ACM Digital Library (cookies)
  191. - [ ] OpenReview
  192. - [ ] PLOS / PMC / Frontiers / MDPI
  193. - Stability & Quality
  194. - [x] Configurable Zotero DB path (ENV + ~/.zotlink/config.json)
  195. - [x] HTTP fallback when browser fails (Windows compatibility)
  196. - [x] PDF download retry mechanism (3 retries with exponential backoff)
  197. - [ ] Windows playwright optimization (current limitation: Python asyncio ProactorEventLoop + MCP event loop nesting)
  198. - [ ] Post-save title correction when placeholder detected
  199. - [ ] Enhanced PDF heuristics and alternative URL strategies
  200. - [ ] Crossref DOI enrichment as fallback
  201. - [ ] Unified error taxonomy with auto-retry/backoff
  202. - Integration & DX
  203. - [ ] Cookie sync bookmark flow for Nature-family and other publishers
  204. - [ ] Example templates for Claude Desktop / Cherry Studio
  205. - [ ] Extended MCP interoperability docs and samples
  206. - [ ] CI and tests (unit/integration) for extractors
  207. - [ ] Packaged releases (optional)
  208. ## 📄 License
  209. MIT (see SPDX identifier in packaging metadata)
  210. ## 🌟 GitHub Star History
  211. <div align="center">
  212. [![Star History Chart](https://api.star-history.com/svg?repos=tonybotni/zotlink&type=Date)](https://star-history.com/#tonybotni/zotlink&Date)
  213. Made with ❤️ for Zotero community
  214. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.