Zotero MCP Agent

An MCP server that allows an LLM to research online papers, manage your Zotero library, and export knowledge bases.

Installation

1. Install Dependencies:

   pip install -r requirements.txt
   

   (Or use uv sync if using uv)

2. Configuration:

   • Copy .env.example to .env:

     cp .env.example .env
     

   • Fill in your keys in .env (Zotero API Key, LLM Key, Tavily Key).
   • Proxy: If you are in a restricted network environment (e.g. using v2rayN), ensure HTTP_PROXY and HTTPS_PROXY are set in .env.

Usage with Chatbox / Claude Desktop

To use this MCP server, you need to configure your client to run the server script.

Command

The server runs via standard input/output (stdio).

Command: python Arguments: [absolute/path/to/main.py]

Example configuration for Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "zotero-agent": {
      "command": "python",
      "args": [
        "D:/Yan2file/zotero-mcp/main.py"
      ],
      "env": {
        "PYTHONPATH": "D:/Yan2file/zotero-mcp"
      }
    }
  }
}

> [!IMPORTANT]
> **Windows Users**: If you encounter errors like `[Errno 2] No such file or directory` where the path looks mashed together:
> 1. Use **forward slashes** (`/`) in your paths.
> 2. Point to `main.py` in the root folder, NOT `src/server.py`.
> Example: `D:/Yan2file/zotero-mcp/main.py`

*Note: You might need to use the full path to your python executable if it's in a virtual environment (e.g. `D:/Yan2file/zotero-mcp/.venv/Scripts/python.exe`).*

## Available Tools

-   `search_online_papers(query, download=True)`: Search and download PDFs.
-   `read_local_paper(file_path)`: Read the text content of a downloaded PDF.
-   `read_zotero_item(item_key)`: Read the content of a Zotero item by its Key (e.g. `ABCD1234`).
-   `search_local_library(query)`: Search your Zotero library.
-   `export_knowledge_base(output_path)`: Export Zotero items to Markdown.

## Example Prompts

-   "Search for the latest papers on LLM Agents and download two of them."
-   "Download the paper 'Attention is All You Need' and summarize its key contributions."