zoty

KO | EN

gitlite — search

#javascript #react #golang #android #machine-learning #rust #deep-learning #linux #docker #nodejs #awesome #cli #openai #mcp

(★ 15)

Lightweight Zotero MCP server for AI agents

zoty Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# zoty

Lightweight Zotero MCP server for AI agents.

![Zoty demo](https://raw.githubusercontent.com/eric-tramel/zoty/main/assets/zoty-demo.gif)

## What it does

MCP server that connects AI agents to your local Zotero library. Provides 8 tools: BM25-ranked search over titles, abstracts, and indexed attachment full text, within-item passage search, collection browsing, item lookup, BibTeX plus formatted citation export for item keys returned by search, and paper ingestion by arXiv ID or DOI with automatic PDF attachment.

## Requirements

- Python 3.10+
- Zotero desktop running (Zotero 8 is the default target; Zotero 7 is also supported)
- Zotero local API enabled: Zotero Settings > Advanced > Config Editor > set `extensions.zotero.httpServer.localAPI.enabled` to `true`
- [Zoty Bridge plugin](#zoty-bridge-plugin) installed (for PDF attachment and collection assignment)

## Add to Your Agent

### Claude Code

Add from the command line:

```bash
claude mcp add zoty -- uvx zoty mcp
```

Add to your `.mcp.json` or `~/.claude/settings.json`:

```json
{
  "mcpServers": {
    "zoty": {
      "command": "uvx",
      "args": ["zoty", "mcp"]
    }
  }
}
```

### Codex

Add from the command line:

```bash
codex mcp add zoty -- uvx zoty mcp
```

Add to your `~/.codex/config.toml`:

```toml
[mcp_servers.zoty]
command = "uvx"
args = ["zoty", "mcp"]
```

## Installation

Requires [uv](https://docs.astral.sh/uv/).

Run without installing (recommended for MCP setups):

```bash
uvx zoty mcp
```

Install persistently:

```bash
uv tool install zoty
```

Upgrade an installed copy:

```bash
uv tool upgrade zoty
```

If you run zoty with `uvx` instead of installing it, refresh to the latest published version with:

```bash
uvx --refresh zoty --version
uvx --refresh zoty doctor
uvx --refresh zoty setup
```

From a local checkout:

```bash
uv run zoty mcp

# Or install from source as a tool
uv tool install .
```

The Python package provides the user CLI and MCP server through PyPI. The Zotero
bridge plugin is distributed as a bundled XPI inside the Python package and as a
GitHub Releases asset; future bridge updates are advertised through the Zotero
update manifest published with each release.

## PDF Reading Advice for Agents

For best results when coding agents open attachment filepaths from zoty, make sure `poppler` and the associated Poppler utilities are installed on the machine. In practice this usually means tools like `pdftotext`, `pdfinfo`, and `pdftoppm` are available on `PATH`.

This is especially important for Claude Code, which uses these utilities to read PDF pages efficiently. Without them, agents may still be able to open the PDF files themselves, but page extraction tends to be slower and less reliable.

Typical installs:

```bash
# macOS
brew install poppler

# Ubuntu / Debian
sudo apt-get install poppler-utils
```

## Zoty Bridge Plugin

A tiny Zotero 7/8/9 plugin that lets zoty execute JavaScript inside Zotero's privileged context. This is needed for operations that can't go through the REST API: PDF attachment and collection assignment both require writing to Zotero's SQLite database, which locks out external processes. The bridge sidesteps this by running JS inside Zotero itself.

### Install the plugin

1. Locate the bundled XPI, download `zoty-bridge.xpi` from the [latest release](https://github.com/eric-tramel/zoty/releases/latest), or build it yourself:
   ```bash
   uvx --refresh zoty setup --download-only
   ```
   ```bash
   uvx --refresh zoty setup
   ```
   ```bash
   make build
   ```
2. In Zotero: Tools > Plugins, then drag `zoty-bridge.xpi` onto the Plugins window.
3. Restart Zotero.
4. Confirm the bridge is running:
   ```bash
   uvx --refresh zoty doctor
   ```

`zoty setup` is a guided, safe default flow. It checks Zotero's local API,
checks the bridge endpoint, points you at the packaged XPI, and tells you the
next concrete action. `zoty setup --check` is equivalent to diagnostics without
changes. Advanced local development can use `zoty setup --install-profile`, but
that command refuses to copy into the Zotero profile while Zotero is running.

Current bridge releases include a Zotero update manifest, so future bridge updates can be detected by Zotero after this XPI is installed.

If you upgraded to Zotero 9 with an older bridge capped at Zotero 8, Zotero may show the bridge as disabled. Install the latest `zoty-bridge.xpi` from the Plugins window, restart Zotero, and enable the bridge if Zotero leaves it disabled after reinstalling.

For local development only, you can also install the built XPI from the command line. Quit Zotero first, then run this from the repository root:

```bash
ZOTERO_PROFILE="$(
  python3 - <<'PY'
from configparser import ConfigParser
from pathlib import Path

root = Path.home() / "Library/Application Support/Zotero"
profiles = ConfigParser()
profiles.read(root / "profiles.ini")

for section in profiles.sections():
    if section.startswith("Profile") and profiles.get(section, "Default", fallback="0") == "1":
        path = Path(profiles.get(section, "Path"))
        print(root / path if profiles.get(section, "IsRelative", fallback="1") == "1" else path)
        break
else:
    raise SystemExit("No default Zotero profile found")
PY
)"
mkdir -p "$ZOTERO_PROFILE/extensions"
cp zotero-plugin/dist/zoty-bridge.xpi "$ZOTERO_PROFILE/extensions/zoty-bridge@zoty.dev.xpi"
```

The bridge runs an HTTP server on `localhost:24119` when Zotero is open. No configuration needed.

## Tools

| Tool | Description |
|------|-------------|
| `search_library` | Find which items in your Zotero library match a keyword query, ranked by BM25 over title, abstract, and indexed attachment full text, with optional plain-text snippets, attachment counts, collection filtering, collection key/name pairs, and case-insensitive item type values like `journalArticle`, `preprint`, `conferencePaper`, `book`, `bookSection`, `thesis`, `report`, and `webpage` |
| `search_within_item` | Find which passages within one or more known items match a keyword query, using `search_library` results to drill into a specific paper or compare several papers; top-level item summaries carry parent titles, and per-match parent `key` is only repeated for multi-item ranking |
| `list_collections` | List all collections with keys, names, and item counts |
| `list_collection_items` | List items in a specific collection, including collection key/name pairs on each item |
| `get_item` | Full metadata for a single `item_key` or batch `item_keys`; use the `key` field from `search_library`, `list_collection_items`, or `get_recent_items` results. Single-key requests keep the detailed item payload, while batch requests return compact item records with `items` plus optional per-item `errors` |
| `get_bibtex_and_citation_for_items` | BibTeX plus formatted citation and bibliography text for a single `item_key` or batch `item_keys`; use the `key` field from `search_library`, `list_collection_items`, or `get_recent_items` results. Both can be combined and at least one must be provided |
| `get_recent_items` | Recently added items, sorted by date, with collection key/name pairs on each item |
| `add_paper` | Add a paper by arXiv ID or DOI with automatic PDF download and collection-scoped duplicate prevention |

Attachment payloads include `linkMode` as a descriptive string (`imported_file`, `imported_url`, `linked_file`, or `linked_url`) instead of Zotero's internal numeric codes.

## How it works

Read operations still use [pyzotero](https://github.com/urschrei/pyzotero) for collection/item APIs, but search now runs off a persistent sidecar index under `~/.cache/zoty/fulltext-index`. zoty reads Zotero metadata from `zotero.sqlite` in immutable mode, reuses Zotero's extracted attachment text caches (`.zotero-ft-cache`) for PDF/EPUB/HTML full text, chunks that text locally, and rebuilds immutable BM25 snapshots in the background. At startup zoty loads the active snapshot synchronously if one exists, then queues a refresh when Zotero content changed.

Write operations use the Zotero connector endpoint (`/connector/saveItems`) to create metadata items. PDF attachment and collection assignment go through the zoty-bridge plugin, which executes JavaScript in Zotero's privileged context. The same bridge is used as a thin control plane to ask Zotero to generate missing full-text caches when needed; zoty does not add plugin-owned tables to `zotero.sqlite` or transfer raw attachment text through the bridge. This two-path design exists because Zotero's SQLite database uses exclusive locking -- external processes can read it (immutable mode) but not write to it while Zotero is running.

arXiv traffic is throttled internally to respect arXiv's access policy. Concurrent `add_paper` calls queue transparently: metadata requests serialize with a 3-second gap, and arXiv PDF downloads are rate-limited separately.

## Development

```bash
make build          # build zotero-plugin/dist/zoty-bridge.xpi and zoty-bridge-updates.json
make verify-build   # rebuild plugin artifacts and fail if committed artifacts are stale
make test    # run Python unit tests
```

Release authors should follow [RELEASING.md](RELEASING.md). The bridge XPI and Zotero update manifest are deterministic build outputs and are checked by CI.

With Zotero running and zoty-bridge installed, run the local MCP smoke test:

```bash
uv run scripts/smoke_mcp.py
```

The smoke test is intentionally not part of `make test` because it depends on
the local Zotero profile and library contents. See the script docstring for
environment variables that pin item/collection keys or opt into duplicate-only
`add_paper` testing.

## License

MIT

## Rate Limiting Across Sessions

zoty rate-limits arXiv traffic inside the running MCP server process. If several `add_paper` calls reach the same server at once, zoty queues them and drains metadata requests at arXiv-safe speed.

That limiter is not shared across separate zoty processes. If you start one zoty instance per agent, session, or editor window, each process will enforce its own limit and the combined request rate can still exceed arXiv policy.

If you expect multiple sessions to pull papers at the same time, start one long-lived zoty server and point all clients at that same instance.

Start one shared local server:

```bash
zoty mcp --transport streamable-http --host 127.0.0.1 --port 8000
```

The shared MCP endpoint will be:

```text
http://127.0.0.1:8000/mcp
```

If you want a different endpoint path:

```bash
zoty mcp \
  --transport streamable-http \
  --host 127.0.0.1 \
  --port 8000 \
  --streamable-http-path /zoty-mcp
```

Then point every client at the same URL:

```text
http://127.0.0.1:8000/zoty-mcp
```

For clients that support remote MCP servers by URL, the config should look like this:

```json
{
  "mcpServers": {
    "zoty": {
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}
```

Avoid this pattern when multiple sessions may import papers in parallel, because it starts a separate zoty process per client:

```json
{
  "mcpServers": {
    "zoty": {
      "command": "zoty",
      "args": ["mcp"]
    }
  }
}
```

Recommended boot sequence:

1. Boot Zotero and make sure the Zotero connector and `zoty-bridge` plugin are available.
2. Start one shared zoty server with `zoty mcp --transport streamable-http`.
3. Configure each agent or MCP client to connect to that existing server URL instead of launching its own copy.
4. Let the shared server serialize arXiv metadata lookups and rate-limit arXiv PDF downloads for everyone.

This keeps the agent-side behavior simple: tool calls may take a bit longer under load, but they will queue naturally instead of hammering `export.arxiv.org`.

zoty

zoty Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

zoty

zoty Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README