Zotero MCP

🚀 Zotero 的 Model Context Protocol (MCP) 服務器

本項目是一個基於 Python 的服務器，實現了 Model Context Protocol (MCP) 與 Zotero 的集成。藉助該服務器，您能夠通過 AI 助手訪問 Zotero 文獻庫，實現了一組功能雖小但實用的交互操作，可與 MCP 客戶端 進行通信。

🚀 快速開始

此 MCP 服務器提供了以下工具，可通過任何 MCP 客戶端或 MCP Inspector 發現和訪問：

• zotero_search_items：使用文本查詢在您的 Zotero 文獻庫中搜索項目。
• zotero_item_metadata：獲取特定 Zotero 項目的詳細元數據信息。
• zotero_item_fulltext：獲取特定 Zotero 項目的全文內容（例如 PDF 文件）。

每個工具都會返回包含相關 Zotero 項目信息的格式化文本，AI 助手（如 Claude）可以按順序使用它們，先搜索項目再獲取其元數據或全文內容。

✨ 主要特性

• 實現 MCP 與 Zotero 的集成，支持通過 AI 助手訪問 Zotero 文獻庫。
• 提供多個實用工具，方便對 Zotero 文獻庫進行搜索、獲取元數據和全文內容。
• 支持與本地 API 或遠程 Web API 通信，提供多種安裝方式。

📦 安裝指南

此服務器可以與 Zotero 的本地 API 或遠程 Web API 通信，以下是兩種安裝方式：

方式一：使用 Docker 容器

在 mcp.json 文件中添加以下配置，替換佔位符為您的實際 API 密鑰和文獻庫 ID：

{
  "mcpServers": {
    "zotero": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e", "ZOTERO_API_KEY=PLACEHOLDER", // 替換為您的 API 密鑰
        "-e", "ZOTERO_LIBRARY_ID=PLACEHOLDER", // 替換為您的文獻庫 ID
        "ghcr.io/kujenga/zotero-mcp:main"
      ]
    }
  }
}

方式二：本地安裝

1. 克隆此倉庫。
2. 使用 uv 安裝依賴項，運行命令：

   uv sync
   

3. 在項目根目錄創建一個 .env 文件，包含以下環境變量：

# 使用本地 API 時
ZOTERO_API=local

# 或使用遠程 Web API 時
ZOTERO_API_KEY=your_api_key_here
ZOTERO_LIBRARY_ID=your_library_id_here

📚 詳細文檔

開發信息

要進行開發或貢獻代碼，請按照以下步驟操作：

1. 克隆此倉庫。
2. 使用 uv 安裝依賴項，運行命令：

   uv sync
   

3. 在項目根目錄創建一個 .env 文件，包含所需的環境變量。

啟動 MCP Inspector 進行本地開發：

npx @modelcontextprotocol/inspector uv run zotero-mcp

要測試與 Claude Desktop 的集成，請在您的 Claude 配置中添加以下內容，將 /path/to 替換為實際路徑：

{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp/.venv/bin/zotero-mcp",
      "env": {
        // 添加所需的環境變量配置
      }
    }
  }
}

運行測試

要運行測試套件，請運行命令：

uv run pytest

Docker 開發

使用以下命令構建容器鏡像：

docker build . -t zotero-mcp:local

要通過 Inspector 測試容器，請運行命令：

npx @modelcontextprotocol/inspector \
    -e ZOTERO_API_KEY=$ZOTERO_API_KEY \
    -e ZOTERO_LIBRARY_ID=$ZOTERO_LIBRARY_ID \
    docker run --rm -i \
        --env ZOTERO_API_KEY \
        --env ZOTERO_LIBRARY_ID \
        zotero-mcp:local

相關文檔

• https://modelcontextprotocol.io/tutorials/building-mcp-with-llms
• https://github.com/modelcontextprotocol/python-sdk
• https://pyzotero.readthedocs.io/en/latest/
• https://www.zotero.org/support/dev/web_api/v3/start