# Zotero-MCP-lite 快速設定

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

## 前置需求（Mac）

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

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

## 安裝步驟（Mac）

> Windows 使用者請改看 [windows_install_guide.md](windows_install_guide.md)。

1. 把整個專案資料夾複製到 Mac 任意位置（從 GitHub 下載 ZIP 解壓縮的話，資料夾名稱通常是 `Zotero-MCP-lite-main`，下面的範例都以它為準）
2. 打開終端機 (Terminal)，在資料夾內執行：
   ```bash
   uv sync
   ```
3. 修改 `.mcp.json` 裡的路徑：
   - 把 `/PATH/TO/Zotero-MCP-lite` 改成實際路徑
4. 如果 Zotero 資料夾不在預設位置 `~/Zotero/`，請在 Claude 的 MCP 設定中加入 `env` 欄位：
   ```json
   {
     "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](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` 應修改為：

   ```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` 到專案資料夾，再執行：

```bash
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](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