# Zotero MCP Server

An MCP (Model Context Protocol) server that gives Claude full read/write access to your [Zotero](https://www.zotero.org/) reference library. Search your library, browse collections, add articles, and organize references — all through natural language.

Built with the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) and [pyzotero](https://github.com/urschrei/pyzotero).

## Tools

### Read
| Tool | Description |
|------|-------------|
| `search_library` | Search your Zotero library by keyword, title, author, or phrase |
| `get_collections` | List all collections (folders) with keys and item counts |
| `get_collection_items` | Get all items in a specific collection |
| `get_item_details` | Get full metadata for a specific item by key |
| `get_recent_items` | Get the most recently added items |

### Write
| Tool | Description |
|------|-------------|
| `add_article` | Add a journal article to your library (pairs well with CrossRef, Scopus, ERIC, etc.) |
| `add_multiple_articles` | Batch-add articles from search results |
| `create_collection` | Create a new collection or sub-collection |
| `add_item_to_collection` | Add an existing item to a collection |

## Setup

### 1. Get Zotero API credentials

1. Go to [zotero.org/settings/keys](https://www.zotero.org/settings/keys)
2. Create a new API key with read/write access to your library
3. Note your user ID (shown on the same page)

### 2. Install

```bash
cd zotero-mcp-server
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

Or run directly with [uv](https://github.com/astral-sh/uv) (dependencies are declared inline):

```bash
uv run server.py
```

### 3. Add to Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "zotero": {
      "command": "/path/to/zotero-mcp-server/venv/bin/python",
      "args": ["/path/to/zotero-mcp-server/server.py"],
      "env": {
        "ZOTERO_API_KEY": "your-api-key",
        "ZOTERO_USER_ID": "your-user-id",
        "ZOTERO_LIB_TYPE": "user"
      }
    }
  }
}
```

Or with uv:

```json
{
  "mcpServers": {
    "zotero": {
      "command": "uv",
      "args": ["run", "/path/to/zotero-mcp-server/server.py"],
      "env": {
        "ZOTERO_API_KEY": "your-api-key",
        "ZOTERO_USER_ID": "your-user-id",
        "ZOTERO_LIB_TYPE": "user"
      }
    }
  }
}
```

## Usage examples

- "Search my Zotero library for papers on curiosity"
- "Show me my Zotero collections"
- "Add this CrossRef result to my Zotero library"
- "Create a new collection called 'Literature Review' and add these 5 papers to it"
- "What are the most recent items I've added to Zotero?"

## Group libraries

To connect to a Zotero group library instead of your personal one, set `ZOTERO_LIB_TYPE=group` and use the group ID as `ZOTERO_USER_ID`.

## License

MIT