# Zotero MCP Server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server for [Zotero](https://www.zotero.org/), enabling LLM-powered tools like Claude Desktop, Claude Code, and Cursor to interact with your academic library.

## Features

### Tools
- **search_papers** - Search papers by keyword, title, or author
- **add_arxiv_paper** - Add papers to Zotero by arXiv ID or URL
- **update_metadata** - Update metadata fields of existing items
- **get_item** - Get detailed information about a specific item
- **get_collection_items** - List items in a collection
- **get_recent_items** - Get recently added items

### Resources
- **zotero://recent** - Recently added items
- **zotero://collection/{key}** - Items in a specific collection (dynamic)

### Prompts
- **literature_review** - Generate structured literature review template from collection papers
- **paper_summary** - Summarize a specific paper with structured analysis

## Quick Start

### Prerequisites

- Python 3.10+
- [Zotero account](https://www.zotero.org/) with API access
- Get your API key at https://www.zotero.org/settings/keys

### Installation

```bash
git clone https://github.com/awsl5714/zotero-mcp-server.git
cd zotero-mcp-server
pip install -e .
```

### Configuration

```bash
cp .env.example .env
# Edit .env with your Zotero credentials
export ZOTERO_LIBRARY_ID=your-library-id
export ZOTERO_API_KEY=your-api-key
export ZOTERO_LIBRARY_TYPE=user  # or "group"
```

### Claude Desktop Integration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_LIBRARY_ID": "your-library-id",
        "ZOTERO_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Claude Code Integration

Add to your Claude Code MCP settings:

```json
{
  "mcpServers": {
    "zotero": {
      "command": "zotero-mcp",
      "env": {
        "ZOTERO_LIBRARY_ID": "your-library-id",
        "ZOTERO_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Usage Examples

Once connected, you can use natural language in Claude:

- "Search my Zotero library for papers about transformer architectures"
- "Add this arXiv paper to my library: 2301.00234"
- "Write a literature review based on my 'Deep Learning' collection"
- "Update the tags for paper KEY123 to include 'NLP' and 'attention'"

## Tech Stack

| Component | Technology |
|-----------|-----------|
| Protocol | [MCP SDK](https://github.com/modelcontextprotocol/python-sdk) |
| Zotero API | [pyzotero](https://github.com/urschrei/pyzotero) |
| Validation | Pydantic v2 |
| HTTP | httpx |

## Project Structure

```
src/zotero_mcp/
├── server.py        # MCP server with Tools, Resources, Prompts
├── zotero_client.py # Zotero API wrapper
└── config.py        # Environment-based configuration
```

## License

MIT