io.github.piiinpiiins/zotero-mcp-local

Zotero-MCP-lite 快速設定

這是一個提供給支援 Model Context Protocol (MCP) 客戶端使用的伺服器軟體，讓 AI 能夠具備讀取與搜尋您本機 Zotero 書目資料庫的技能。目前主流多搭配 Claude Desktop App 使用。

前置需求（Mac）

• Python >= 3.10：建議透過 Homebrew 安裝 (brew install python)，或至 Python 官網 下載安裝檔。
• uv 套件管理工具：打開終端機輸入 curl -LsSf https://astral.sh/uv/install.sh | sh 或 brew install uv
• Zotero 資料夾（含 zotero.sqlite）已放置在本機電腦上

Windows 使用者請改看 windows_install_guide.md，裡面有完整的前置需求、安裝步驟與除錯說明。

安裝步驟（Mac）

Windows 使用者請改看 windows_install_guide.md。

1. 把整個專案資料夾複製到 Mac 任意位置（從 GitHub 下載 ZIP 解壓縮的話，資料夾名稱通常是 Zotero-MCP-lite-main，下面的範例都以它為準）
2. 打開終端機 (Terminal)，在資料夾內執行：

    uv sync

3. 修改 .mcp.json 裡的路徑：
   • 把 /PATH/TO/Zotero-MCP-lite 改成實際路徑

4. 如果 Zotero 資料夾不在預設位置 ~/Zotero/，請在 Claude 的 MCP 設定中加入 env 欄位：

    {
      "mcpServers": {
        "zotero": {
          "command": "uv",
          "args": [
            "--directory",
            "/PATH/TO/Zotero-MCP-lite",
            "run",
            "python",
            "-m",
            "src.zotero_mcp.server"
          ],
          "env": {
            "ZOTERO_DB_PATH": "/your/path/to/zotero.sqlite"
          }
        }
      }
    }

   不要用 export ZOTERO_DB_PATH=... 來設定：在終端機下的 export 只對那個視窗有效，從 Launchpad 或 Dock 開啟的 Claude Desktop 是另一個獨立的程序，讀不到。要讓 Claude 認得路徑，只能寫在設定檔的 env 欄位裡。（若只是想用下面的「驗證」指令在終端機測試，才需要 export。）

如何連接到 Claude Desktop（Mac）

Windows 使用者請改看 windows_install_guide.md。

完成上方的「前置需求」與「安裝步驟」後，透過以下步驟將程式連接至 Claude：

1. 開啟 Claude Desktop 的設定檔 claude_desktop_config.json（二擇一）：

   方法 A — 從 Claude Desktop App 內開啟（推薦）：

   1. 開啟 Claude Desktop App
   2. 點擊左上角選單 Claude → Settings
   3. 點選左側的 Developer
   4. 點擊 Edit Config 按鈕，系統會自動用文字編輯器打開 claude_desktop_config.json

   方法 B — 手動開啟檔案：打開 Finder，按 Cmd + Shift + G，貼上 ~/Library/Application Support/Claude/，找到 claude_desktop_config.json 並用文字編輯器開啟。若檔案不存在，請自行新建。

2. 將本資料夾中 .mcp.json 的內容複製並合併至 claude_desktop_config.json 裡面

3. 修改路徑：務必將剛貼上內容中的 /PATH/TO/Zotero-MCP-lite 更改為本專案資料夾的實際絕對路徑

   例如，若您將資料夾放在桌面，路徑為 /Users/huang/Desktop/Zotero-MCP-lite-main，則 claude_desktop_config.json 應修改為：

    {
      "mcpServers": {
        "zotero": {
          "command": "uv",
          "args": [
            "--directory",
            "/Users/huang/Desktop/Zotero-MCP-lite-main",
            "run",
            "python",
            "-m",
            "src.zotero_mcp.server"
          ]
        }
      }
    }

   注意：如果您的 claude_desktop_config.json 裡已有其他設定（如 coworkScheduledTasksEnabled 等），請確保 mcpServers 與它們平行放置，不要把其他設定放進 mcpServers 裡面。

   如果您在「安裝步驟」第 4 步加過 env（Zotero 不在預設位置）：上面這份範例沒有 env，請不要拿它整段覆蓋掉您的設定，把 "env": { "ZOTERO_DB_PATH": "..." } 那段保留在 "args" 後面即可。

4. 完全重啟 Claude：儲存設定檔後，用 Cmd + Q 完全結束 Claude Desktop（關掉視窗不算），再重新開啟。點開輸入框旁的「搜尋與工具」選單，看到 zotero 即表示伺服器啟動成功！（舊版 Claude Desktop 是在右下角顯示 🔌 或鐵鎚圖示。）

驗證

先 cd 到專案資料夾，再執行：

uv run python -m src.zotero_mcp.server

怎麼判斷成功：這個伺服器是靠標準輸入輸出溝通的，正常啟動時不會印出任何訊息，游標會停在那裡等待輸入。只要它沒有馬上跳回提示字元、也沒有噴出錯誤，就表示啟動成功，按 Ctrl + C 結束即可。反之，如果指令一秒內就結束並跳回提示字元，代表伺服器沒能啟動。

可能會看到一行 RuntimeWarning: 'src.zotero_mcp.server' found in sys.modules...，這是 Python 的提醒訊息，不影響運作，可以忽略。

除錯

Windows 常見問題請看 windows_install_guide.md 的除錯章節。

Mac 系統常見問題

1. 找不到 Zotero 資料庫 (zotero.sqlite)
   • 問題：不知道 Zotero 資料庫存放在哪裡，無法確定路徑。
   • 解法：預設路徑通常為 ~/Zotero/zotero.sqlite。如果找不到，請打開終端機 (Terminal) 輸入以下指令搜尋：
     • Spotlight 快速搜尋（推薦）：mdfind -name "zotero.sqlite"
     • 個人目錄深度搜尋：find ~ -name "zotero.sqlite" 2>/dev/null

進階版（Pro）

需要更完整的研究分析工具嗎？Pro 版多了四個工具：Connected Papers 關聯圖與視覺化、跨論文整理作者自述的研究限制與未來方向、跨論文關鍵段落搜尋（附頁碼）。

👉 Zotero-MCP Pro（US$30 一次買斷，含中英安裝指南與診斷工具）：https://3718181853007.gumroad.com/l/calm-study-partner