Metadata-Version: 2.4
Name: zotero-api-mcp
Version: 0.0.1
Summary: A clean, one-to-one MCP server for the Zotero API — no AI bloat, just the API
Project-URL: Homepage, https://github.com/siebert-julien/zotero-api-mcp
Project-URL: Repository, https://github.com/siebert-julien/zotero-api-mcp
Project-URL: Issues, https://github.com/siebert-julien/zotero-api-mcp/issues
Author-email: Julien Siebert <julien.siebert@iese.fraunhofer.de>
License: MIT
License-File: LICENSE
Keywords: mcp,model-context-protocol,reference-manager,zotero
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.12
Requires-Dist: defusedxml>=0.7.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: pyzotero>=1.5.0
Requires-Dist: requests>=2.28.0
Requires-Dist: tenacity>=8.0.0
Provides-Extra: dev
Requires-Dist: bump-my-version>=0.24.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: tox>=4.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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`

## 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

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

## 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.
