ZotLink by TonybotNi - MCP Server

ZotLink

MCP Server for Zotero Connector

🌍 Language / 语言选择: |

🔗 ZotLink

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!

✨ Core Features

🌐 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

🚀 Quick Start

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:

📝 Manual Configuration Examples (click to expand)

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.).

🧰 Available Tools

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

📁 Logging

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

🌐 Browser Mode

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

Advanced: Custom Zotero Paths

🔧 Environment Variable Configuration (click to expand)

Recommended - Single directory:

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

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

Advanced - Separate paths:

# 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'

Local config file ~/.zotlink/config.json:

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

Configuration precedence: ENV vars > MCP env config > local config file > auto-detection

🧩 Supported Sources (Open)

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.

🧰 Troubleshooting

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

🧪 Development

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.

TonybotNi/ZotLink