zotero-mcp-local 0.1.0

MCP Server for accessing and analyzing your local Zotero library with AI agents

Zotero MCP

A Model Context Protocol (MCP) server that connects AI agents (Claude, etc.) to your local Zotero library. Search papers, read PDFs, find related work — all through natural language.

一個 Model Context Protocol (MCP) 伺服器，讓 AI Agent（Claude 等）能直接存取你本地的 Zotero 資料庫。用自然語言搜尋文獻、閱讀 PDF、尋找相關論文。

---

English

Features

Zotero Local Tools

• search_items(query) — Search by title or author
• get_item_details(item_key) — Get full metadata (abstract, authors, DOI, etc.)
• find_related_papers(item_key, limit) — Find related papers using 5-dimensional composite similarity (shared collections 30%, tags 25%, fulltext word overlap 25%, authors 10%, venue 10%)
• get_pdf_text(item_key, max_pages) — Extract text from PDF attachments

Resources

• zotero://library/info — Library statistics
• zotero://library/items — Recent 50 items
• zotero://items/{key} — Item details by key

Installation

Prerequisites

• Zotero (installed, default database path ~/Zotero/zotero.sqlite)

• uv — Python package manager:

  Mac/Linux:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

  Windows (PowerShell):

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

  After installing, restart your terminal and verify with uv --version.

  If the installation was successful, it will display the version number, e.g.:

  uv 0.6.6 (Homebrew 2025-03-04)
  

  If you see command not found, it means uv was not added to your PATH correctly. Check your shell config file (~/.zshrc or ~/.bashrc) to ensure the uv path is included.

Configure Claude Desktop

Open Claude Desktop, go to Settings → Developer → Edit Config, and paste the following into claude_desktop_config.json:

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["zotero-mcp-local"]
    }
  }
}

Save the file and restart Claude Desktop. Go to Settings → Developer, you should see the Zotero MCP server with a "running" status:

(Optional) Custom Zotero database path: If your database is not at the default location, add env:

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["zotero-mcp-local"],
      "env": {
        "ZOTERO_DB_PATH": "/your/path/to/zotero.sqlite"
      }
    }
  }
}

Usage

Once configured, just ask Claude naturally:

• "Search my Zotero library for papers about reminiscence therapy"
• "Show me the details of paper ABCD1234"
• "Find papers related to ABCD1234 in my library"
• "Extract the text from the PDF of paper XYZ789"

How It Works

• Database Access: Reads your local Zotero SQLite database via a temporary copy (read-only, never modifies your data).
• Related Papers Algorithm: Computes similarity using 5 weighted dimensions — shared collections, tags, fulltext word overlap (IDF-filtered), shared authors, and publication venue.

Troubleshooting

Problem	Solution
Server not showing "running"	Restart Claude Desktop after saving config
"Zotero database not found"	Check ZOTERO_DB_PATH or ensure Zotero is installed
First command fails	Try again — the server may need a moment to initialize

Note: What is zotero.sqlite?

zotero.sqlite is a SQLite database file where Zotero stores all your library data — titles, authors, tags, collections, DOIs, notes, and more. Unlike server-based databases (MySQL, PostgreSQL), SQLite keeps everything in a single file, and no separate server process is needed.

Zotero MCP reads this file (via a temporary read-only copy) to provide your library data to Claude. It never modifies your original database.

Default location: ~/Zotero/zotero.sqlite

Note: Where should Zotero MCP be installed?

Zotero MCP does not need to be placed in any specific folder. The installation method uses uvx zotero-mcp-local, which automatically downloads and runs the package from PyPI — no manual cloning or file placement required.

You only need to:

1. Install uv
2. Add "command": "uvx", "args": ["zotero-mcp-local"] in your Claude Desktop config

uvx automatically manages the package download and storage (typically under ~/.cache/uv/).

The only path you need to verify is your Zotero database itself, which defaults to ~/Zotero/zotero.sqlite. If it's not at the default location, specify it via the ZOTERO_DB_PATH environment variable.

---

中文說明

功能

Zotero 本地工具

• search_items(query) — 依標題或作者搜尋文獻
• get_item_details(item_key) — 取得完整詮釋資料（摘要、作者、DOI 等）
• find_related_papers(item_key, limit) — 使用五維複合相似度找出相關論文（共同集合 30%、標籤 25%、全文詞彙重疊 25%、作者 10%、出版場所 10%）
• get_pdf_text(item_key, max_pages) — 提取 PDF 附件全文

資源

• zotero://library/info — 資料庫統計資訊
• zotero://library/items — 最近 50 筆文獻
• zotero://items/{key} — 依 Key 取得文獻詳情

安裝

前置需求

• Zotero（已安裝，預設資料庫路徑 ~/Zotero/zotero.sqlite）

• uv — Python 套件管理工具：

  Mac/Linux：

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

  Windows（PowerShell）：

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

  安裝完成後請重新開啟終端機，輸入 uv --version 確認安裝成功。

  如果安裝成功，會顯示版本號，例如：

  uv 0.6.6 (Homebrew 2025-03-04)
  

  如果出現 command not found，表示 uv 未正確加入 PATH，需要檢查 shell 設定檔（~/.zshrc 或 ~/.bashrc）是否有加入 uv 的路徑。

設定 Claude Desktop

開啟 Claude Desktop，前往 Settings → Developer → Edit Config，將以下內容貼入 claude_desktop_config.json：

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["zotero-mcp-local"]
    }
  }
}

儲存後重新啟動 Claude Desktop，前往 Settings → Developer，應可看到 Zotero MCP 伺服器顯示 「running」 狀態：

（選配）自訂 Zotero 資料庫路徑： 若你的資料庫不在預設位置，加入 env：

{
  "mcpServers": {
    "zotero": {
      "command": "uvx",
      "args": ["zotero-mcp-local"],
      "env": {
        "ZOTERO_DB_PATH": "/your/path/to/zotero.sqlite"
      }
    }
  }
}

使用範例

設定完成後，直接用自然語言與 Claude 對話：

• 「搜尋我 Zotero 裡關於懷舊治療的文獻」
• 「顯示文獻 ABCD1234 的詳細資訊」
• 「找出我資料庫中與 ABCD1234 相關的論文」
• 「提取 XYZ789 的 PDF 全文」

運作原理

• 資料庫存取： 透過臨時副本讀取 Zotero SQLite 資料庫（唯讀，不會修改你的資料）。
• 關聯論文演算法： 使用五維加權相似度 — 共同集合、標籤、全文詞彙重疊（IDF 過濾）、共同作者、出版場所。

常見問題排除

問題	解決方法
伺服器未顯示 "running"	儲存設定後重新啟動 Claude Desktop
"Zotero database not found"	確認 ZOTERO_DB_PATH 或確保 Zotero 已安裝
第一個指令失敗	再試一次，伺服器可能需要片刻初始化

備註：zotero.sqlite 是什麼？

zotero.sqlite 是一個 SQLite 資料庫檔案，Zotero 將你所有的文獻資料都儲存在這個檔案中 — 包括標題、作者、標籤、集合、DOI、筆記等。與需要啟動伺服器的資料庫（MySQL、PostgreSQL）不同，SQLite 將所有資料存在單一檔案中，不需要額外的伺服器程序。

Zotero MCP 透過臨時的唯讀副本讀取此檔案，將你的文獻資料提供給 Claude 使用。它絕不會修改你的原始資料庫。

預設路徑：~/Zotero/zotero.sqlite

備註：Zotero MCP 應該放在哪裡？

Zotero MCP 不需要放在特定資料夾。安裝方式是用 uvx zotero-mcp-local，uvx 會自動從 PyPI 下載並執行，不需要手動 clone 或放置任何檔案。

使用者只需要：

1. 安裝 uv
2. 在 Claude Desktop 設定中加入 "command": "uvx", "args": ["zotero-mcp-local"]

uvx 會自動管理套件的下載和存放位置（通常在 ~/.cache/uv/ 下）。

唯一需要確認位置的是 Zotero 資料庫本身，預設在 ~/Zotero/zotero.sqlite。如果不在預設位置，才需要透過 ZOTERO_DB_PATH 環境變數指定。

---

License

MIT

---