# zotero-api-mcp

A clean, one-to-one MCP server for the Zotero API, just the API.


## Features

- **22 MCP tools** covering the full Zotero API surface
- **Local API** support (`ZOTERO_LOCAL=true`) — no API key needed
- **Web API** support with interactive setup wizard
- **Full CRUD**: create items by DOI, arXiv, ISBN; update metadata; delete to trash
- **Collections**: create, add/remove items, search
- **Notes & Annotations**: read, create
- **Attachments**: add files or URLs, read metadata
- **Library management**: stats, trash, groups, tags
- **Secure by default**: API key stored with `SecretStr`, XML parsing via `defusedxml`
- **Configuration**: `.env` file support with `ZOTERO_` prefix, `pydantic-settings`
- **Multi-library support**: Query any group or user library per-call without reconfiguring

## Multi-Library Support

All tools accept optional `library_id` and `library_type` keyword parameters to override the default library configured in your environment. This lets you query multiple Zotero group libraries without restarting the server or changing your `.env` file.

**Example**: Query a group library from any tool:

```
zotero_search_items(query="machine learning", library_id="<group-id>", library_type="group")
zotero_get_item("ABC12345", library_id="<group-id>", library_type="group")
zotero_get_collection_items("XYZ99999", library_id="<group-id>", library_type="group")
```

- `library_id` — The Zotero library ID (user ID or group ID)
- `library_type` — Either `"user"` or `"group"`
- Both default to your configured `ZOTERO_LIBRARY_ID` / `ZOTERO_LIBRARY_TYPE` when omitted
- Works with all 22 tools — search, items, collections, notes, annotations, and attachments
- Stateless: each call is independent, no session-level switching needed

## Quick Start

```bash
# Run directly (auto-installs)
uvx zotero-api-mcp serve

# Or install globally
uv tool install zotero-api-mcp
zotero-api-mcp serve
```

### Local Mode (no API key)

Set the environment variable and run:

```bash
ZOTERO_LOCAL=true uvx zotero-api-mcp serve
```

Requires Zotero running with "Allow other applications to access Zotero" enabled in Preferences → Advanced → General.

### Web API Mode

```bash
zotero-api-mcp setup
```

You'll need a Zotero API key from https://www.zotero.org/settings/keys and your library ID.

## MCP Configuration

### VS Code / Cline / Claude Desktop

**Local mode** (read-only, no API key):

```json
{
  "servers": {
    "zotero-api": {
      "type": "stdio",
      "command": "uvx",
      "args": ["zotero-api-mcp", "serve"],
      "env": {
        "ZOTERO_LOCAL": "true"
      }
    }
  }
}
```

**Web API mode** (full read/write, requires API key):

```json
{
  "servers": {
    "zotero-api": {
      "type": "stdio",
      "command": "uvx",
      "args": ["zotero-api-mcp", "serve"],
      "env": {
        "ZOTERO_API_KEY": "<your-api-key>",
        "ZOTERO_LIBRARY_ID": "<your-user-id>",
        "ZOTERO_LIBRARY_TYPE": "user"
      }
    }
  }
}
```

Get your API key at https://www.zotero.org/settings/keys and find your user ID there too. Set `ZOTERO_LIBRARY_TYPE` to `"group"` if your default library is a group.

## Tools

### Search & Discovery (9 tools)
- `zotero_search_items` — Search by query, type, tag, or collection
- `zotero_get_item` — Full details for a specific item
- `zotero_get_item_children` — Notes and attachments for an item
- `zotero_search_collections` — List/search collections
- `zotero_get_collection_items` — Items in a collection
- `zotero_search_tags` — List/search tags
- `zotero_get_trash` — Items in trash
- `zotero_get_library_stats` — Library statistics
- `zotero_get_groups` — Group libraries

### Item Management (5 tools)
- `zotero_add_by_doi` — Add paper by DOI (CrossRef metadata)
- `zotero_add_by_arxiv` — Add paper by arXiv ID
- `zotero_add_by_isbn` — Add book by ISBN (OpenLibrary metadata)
- `zotero_update_item` — Update title, abstract, date, extra
- `zotero_delete_items` — Move items to trash

### Collections (3 tools)
- `zotero_create_collection` — Create a new collection
- `zotero_add_to_collection` — Add items to a collection
- `zotero_remove_from_collection` — Remove items from a collection

### Notes (2 tools)
- `zotero_add_note` — Add a note to an item
- `zotero_read_note` — Read a note's content

### Annotations (1 tool)
- `zotero_read_annotations` — Read PDF annotations for an item

### Attachments (2 tools)
- `zotero_add_attachment` — Attach a file or URL to an item
- `zotero_read_attachment` — Get attachment metadata

## Comparison with other Zotero MCP servers

| Feature | zotero-api-mcp | zotero-mcp (kujenga) | zotero-mcp-lite (xmruuu) | zotero-mcp-server (54yyyu) |
|---|---|---|---|---|
| Tools | **22** | 3 | 9 | ~30 |
| Philosophy | 1:1 API mapping | Minimal | Read-focused | AI-heavy |
| CRUD (create/update/delete) | ✅ | ❌ | ❌ | ✅ |
| DOI/arXiv/ISBN import | ✅ | ❌ | ❌ | ✅ |
| Collection management | ✅ | ❌ | ❌ | ✅ |
| Attachment management | ✅ | ❌ | ❌ | ❌ |
| Local API (no key) | ✅ | ❌ | ✅ | ❌ |
| Semantic search / AI | ❌ | ❌ | ❌ | ✅ |
| Dependencies | 6 | 4 | 9 | 97 |

## Development

See [CONTRIBUTING.md](CONTRIBUTING.md) for full setup and guidelines.

```bash
# Install dependencies (requires uv)
uv sync --group dev

# Run tests
just test         # Quick: current Python
just test-all     # Full: Python 3.12–3.14 via tox

# Version management
just version      # Show current version
just bump-patch   # 0.0.1 → 0.0.2, creates git tag + commit
```

## License

MIT — see [LICENSE](LICENSE) for details.