Metadata-Version: 2.4
Name: zotero-mcp-local
Version: 0.1.3
Summary: MCP Server for accessing and analyzing your local Zotero library with AI agents
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pymupdf>=1.24.0
Description-Content-Type: text/markdown

# Zotero MCP

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 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)](https://modelcontextprotocol.io/) 伺服器，讓 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:**
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
  **Windows (PowerShell):**
  ```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`:

```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:

![Zotero MCP running](docs/claude_desktop_running.png)

> **(Optional) Custom Zotero database path:** If your database is not at the default location, add `env`:
> ```json
> {
>   "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](https://www.sqlite.org/) 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：**
  ```bash
  curl -LsSf https://astral.sh/uv/install.sh | sh
  ```
  **Windows（PowerShell）：**
  ```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`：

```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 MCP running](docs/claude_desktop_running.png)

> **（選配）自訂 Zotero 資料庫路徑：** 若你的資料庫不在預設位置，加入 `env`：
> ```json
> {
>   "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](https://www.sqlite.org/) 資料庫檔案，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

---

[![Buy Me A Coffee](https://img.shields.io/badge/Buy%20Me%20A%20Coffee-support-yellow?style=flat&logo=buy-me-a-coffee)](https://buymeacoffee.com/apinrece)
