ZotLink

MCP Server for Zotero Connector

🌍 Language / 语言选择: 🇺🇸 English | 🇨🇳 中文

A lightweight, production-ready MCP server that brings open scholarly sources into Zotero with one command.

❤️ Like ZotLink? Give it a star 🌟 to support the development!

• 🌐 Open Preprint Coverage: arXiv, CVF (OpenAccess), bioRxiv, medRxiv, chemRxiv
• 🧠 Rich Metadata Extraction: title, authors, abstract, DOI, subjects, comments
• 📄 Smart PDF Attachment: auto-attach when available; validated link fallback
• 📚 One-Click Collection Save: list + save (updateSession, treeViewID: C{id})
• 🧭 Adaptive Browser Strategy: Playwright for tough sites; HTTP for the rest
• 💻 Client Compatibility: Works with Claude Desktop and Cherry Studio
• 🧩 Deep MCP Interoperability: Integrates with literature-related MCPs such as arxiv-mcp-server and Zotero MCP
• 📝 Unified Logging: ~/.zotlink/zotlink.log

pip install zotlink
python -m playwright install chromium

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

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"
      }
    }
  }
}

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!

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

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

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

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

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

• check_zotero_status: Check if Zotero is running and reachable
• get_zotero_collections: List collections (tree view) from the local DB
• save_paper_to_zotero: Save a paper by URL (arXiv/CVF/rxiv), attach PDF/metadata
• extract_arxiv_metadata: Extract full arXiv metadata (title/authors/subjects/DOI/comment)
• Cookie helpers (stubs prepared) for auth-required sources

Logs are written to ~/.zotlink/zotlink.log.

Browser-driven extraction is included by default! All preprint servers (bioRxiv, medRxiv, chemRxiv) work automatically.

The server switches to browser strategy automatically when needed (falls back to HTTP mode on Windows).

Linux may require additional system dependencies:

sudo apt-get install -y libnss3 libatk1.0-0 libatk-bridge2.0-0 libdrm2 libxkbcommon0 libgbm1 libasound2

# macOS/Linux
export ZOTLINK_ZOTERO_ROOT=/Users/yourname/Zotero

# Windows PowerShell
$env:ZOTLINK_ZOTERO_ROOT='C:\Users\YourName\Zotero'

# macOS/Linux
export ZOTLINK_ZOTERO_DB=/Users/yourname/Zotero/zotero.sqlite
export ZOTLINK_ZOTERO_DIR=/Users/yourname/Zotero/storage

# Windows PowerShell
$env:ZOTLINK_ZOTERO_DB='C:\Users\YourName\Zotero\zotero.sqlite'
$env:ZOTLINK_ZOTERO_DIR='C:\Users\YourName\Zotero\storage'

{
  "zotero": {
    "database_path": "/Users/yourname/Zotero/zotero.sqlite",
    "storage_dir": "/Users/yourname/Zotero/storage"
  }
}

• arXiv (preprint)
• CVF (OpenAccess) (CVPR/ICCV/WACV)
• bioRxiv / medRxiv / chemRxiv (preprint servers)

Auth-required sources (e.g., Nature) are planned via bookmark-based cookie sync.

• Zotero not detected: ensure Zotero Desktop is running (port 23119)
• No PDF attached: some pages only expose links; the server falls back to link attachments
• Browser mode errors: verify Playwright is installed and Chromium is available
  • Install error: ensure Python 3.10+ is installed

pip install -e .
python -m playwright install chromium
zotlink  # or: python run_server.py

See docs/DEVELOPMENT.md for code structure, adding new extractors, and release tips.

• Sources

  • arXiv
  • CVF (OpenAccess)
  • bioRxiv
  • medRxiv
  • chemRxiv
  • Nature (cookies)
  • Science (cookies)
  • IEEE Xplore (cookies)
  • Springer (cookies)
  • ACM Digital Library (cookies)
  • OpenReview
  • PLOS / PMC / Frontiers / MDPI

• Stability & Quality

  • Configurable Zotero DB path (ENV + ~/.zotlink/config.json)
  • HTTP fallback when browser fails (Windows compatibility)
  • PDF download retry mechanism (3 retries with exponential backoff)
  • Windows playwright optimization (current limitation: Python asyncio ProactorEventLoop + MCP event loop nesting)
  • Post-save title correction when placeholder detected
  • Enhanced PDF heuristics and alternative URL strategies
  • Crossref DOI enrichment as fallback
  • Unified error taxonomy with auto-retry/backoff

• Integration & DX

  • Cookie sync bookmark flow for Nature-family and other publishers
  • Example templates for Claude Desktop / Cherry Studio
  • Extended MCP interoperability docs and samples
  • CI and tests (unit/integration) for extractors
  • Packaged releases (optional)

MIT (see SPDX identifier in packaging metadata)