zotero-mcp-local 0.1.3

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%)
• list_collections(parent_collection_key) — Browse collection (folder) hierarchy — call with no arguments for top-level, or with a key for sub-collections
• get_collection_items(collection_key) — List all items in a specific collection
• 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:

{
  "preferences": {
    "coworkScheduledTasksEnabled": true,
    "ccdScheduledTasksEnabled": true,
    "sidebarMode": "chat",
    "coworkWebSearchEnabled": true
  },
  "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"
• "Show me all my Zotero collections"
• "What papers are in the 'Background / trend' folder?"

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.

Tested Environment

Software	Version
macOS	14.6 (Sonoma)
Zotero	7.0.32
Claude Desktop	1.1.6452

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%）
• list_collections(parent_collection_key) — 瀏覽集合（資料夾）層級結構 — 不帶參數顯示頂層集合，帶 key 顯示子集合
• get_collection_items(collection_key) — 列出特定集合中的所有文獻
• 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：

{
  "preferences": {
    "coworkScheduledTasksEnabled": true,
    "ccdScheduledTasksEnabled": true,
    "sidebarMode": "chat",
    "coworkWebSearchEnabled": true
  },
  "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 集合」
• 「Background / trend 資料夾裡有哪些論文？」

運作原理

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

測試環境

軟體	版本
macOS	14.6 (Sonoma)
Zotero	7.0.32
Claude Desktop	1.1.6452

常見問題排除

問題	解決方法
伺服器未顯示 "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

---