zotero-headless 1.0.1

Headless Zotero-compatible runtime with CLI, HTTP API, MCP, local desktop interoperability, web sync, qmd-backed semantic search, and support for your agent tool of choice

zotero-headless

zotero-headless is a headless Zotero-compatible runtime with:

• a CLI for operators and scripts
• an HTTP API for apps and services
• an MCP server for agent tools
• a clean-room headless store
• Zotero web sync for user and group libraries
• local Zotero desktop interoperability
• qmd-backed semantic search that refreshes from library changes
• built-in recovery snapshots, restore flows, and backup repositories

It is built for two main deployment shapes:

• desktop interoperability: use an existing Zotero Desktop profile and optionally write supported changes back
• true headless runtime: run the daemon on a machine without Zotero Desktop and expose API or MCP to clients

Quick Setup

1. Install the CLI

uv tool install zotero-headless

or:

pipx install zotero-headless

Main entrypoints:

zotero-headless
zotero-headless-daemon
zotero-headless-mcp

Short aliases:

zhl
zhl-daemon
zhl-mcp

2. Run guided setup

zhl setup start

setup start tries autodiscovery first. On a normal desktop install it will usually find standard Zotero paths automatically, then prompt only for the missing pieces such as API credentials or remote-library selection.

3. Pick the common path that matches your use case

Codex plugin

Best if you want the richest Codex integration, not just raw MCP wiring.

zhl plugin install codex

This installs the local Codex plugin bundle with:

• bundled Zotero skills
• bundled research and sync agents
• bundled MCP config
• a startup status hook

Claude Code

Use the Claude Code plugin bundle.

zhl plugin install claude-code

This installs the repo-local Claude Code plugin bundle and refreshes its bundled .mcp.json from your local settings.

OpenClaw

Use OpenClaw's native plugin system plus the matching skill.

zhl plugin install openclaw
zhl skill install openclaw

zhl plugin install openclaw runs the real OpenClaw plugin install and enable flow against ./plugins/openclaw-plugin-zotero.

Codex or another client with plain MCP only

If you want raw MCP config without the full Codex plugin bundle:

zhl setup add codex --scope user

Other supported setup targets include cursor, claude-desktop, gemini, cline, antigravity, and windsurf.

Headless daemon on a server

If this machine is the runtime host:

zhl-daemon serve --host 0.0.0.0 --port 8787 --sync-interval 300

4. Smoke-test the install

zhl capabilities
zhl daemon status
zhl setup list

If you configured remote sync:

zhl raw sync discover

Most Common Workflows

Search the library

zhl qmd query "papers about retrieval augmented generation"

Use qmd-backed search for exploratory retrieval. Use exact MCP, API, or CLI reads for authoritative metadata.

Pull and push a remote library

zhl raw sync pull --library user:123456
zhl raw sync push --library user:123456
zhl raw sync conflicts --library user:123456

Always inspect conflicts before retrying a failed push.

Import from local Zotero Desktop

zhl local import
zhl local plan-apply --library local:1
zhl local apply --library local:1

Use plan-apply before any local writeback.

Create a safety snapshot

zhl recovery snapshot-create --reason "before bulk edits"
zhl recovery restore-plan --snapshot <snapshot_id> --library group:123
zhl recovery restore-execute --snapshot <snapshot_id> --library group:123 --confirm

Which Interface To Use

CLI

Use the CLI for:

• operator workflows
• shell scripts
• setup and diagnostics
• local administration

Human-facing commands live on the main surface such as setup, doctor, version, and daemon.

For strict machine-oriented automation, use:

zhl raw ...

HTTP API

Use the API for:

• app-to-app integration
• long-running services
• direct agent integrations without MCP
• runtime observability and job inspection

You can expose it with either:

zhl api serve --host 127.0.0.1 --port 8787

or:

zhl-daemon serve --host 127.0.0.1 --port 8787 --sync-interval 300

MCP

Use MCP when your client already speaks MCP and you want native tool use inside:

• Codex
• Claude Code
• Cursor
• Gemini
• Cline
• Windsurf
• similar agent tools

Start the stdio MCP server directly with:

zhl-mcp

Typical Setup Recipes

Desktop machine with Zotero installed and Codex as the client

uv tool install zotero-headless
zhl setup start
zhl plugin install codex

Useful next commands:

zhl local import
zhl qmd query "papers about transformers in NLP"

Standalone headless server

uv tool install zotero-headless
zhl setup start
zhl-daemon serve --host 0.0.0.0 --port 8787 --sync-interval 300

Useful next commands:

curl -s http://127.0.0.1:8787/capabilities
zhl raw sync discover

Claude Code on a project

uv tool install zotero-headless
zhl setup start
zhl plugin install claude-code

OpenClaw

uv tool install zotero-headless
zhl setup start
zhl plugin install openclaw
zhl skill install openclaw

Command Cheat Sheet

Status and diagnostics

zhl version
zhl doctor
zhl capabilities
zhl daemon status
zhl setup list

Client setup

zhl plugin install codex
zhl plugin install claude-code
zhl plugin install openclaw
zhl setup add codex --scope user
zhl skill install codex
zhl skill install openclaw
zhl skill export claude-desktop

Local desktop interoperability

zhl local libraries
zhl local import
zhl local poll
zhl local plan-apply --library local:1
zhl local apply --library local:1

Remote sync

zhl sync discover
zhl sync pull --library user:123456
zhl sync push --library user:123456
zhl sync conflicts --library user:123456

Recovery

zhl recovery repositories
zhl recovery snapshot-create --reason "before risky edit"
zhl recovery restore-plan --snapshot <snapshot_id> --library user:123456
zhl recovery restore-execute --snapshot <snapshot_id> --library user:123456 --confirm

Status

This project is still early-stage, but it already includes:

• a headless SQLite store and change log
• the zotero-headless CLI
• the zotero-headless-daemon runtime
• the zotero-headless-mcp stdio server
• a local HTTP API
• Zotero web sync for user and group libraries
• local Zotero desktop import, polling, and narrow apply support
• remote attachment upload and download for the currently supported paths
• Better BibTeX-oriented citekey compatibility
• qmd export plus semantic search with automatic refresh
• MCP setup helpers and plugin installers for common agent tools
• runtime observability endpoints and background sync status
• recovery snapshots, restore planning, restore execution, and backup replication

Current compatibility baseline:

• Zotero 9.0 (released April 10, 2026) is the newest tracked desktop/runtime baseline for local schema assumptions
• Zotero 9 native citation-key fields are preserved on local reads and writes and attempted on remote writes with fallback behavior
• Zotero's browser-based account login does not replace the Web API key requirement for remote sync

Repository Layout

• src/zotero_headless/: runtime, CLI, API, MCP, sync, and adapter code
• tests/: regression coverage across runtime and tooling surfaces
• docs/: deeper guides and architecture notes
• plugins/: repo-local plugin bundles for supported agent clients
• desktop_helper/: metadata and patch workflow for the optional external Zotero desktop-helper path

Local-only workspace material should live in ignored directories such as:

• .codex/
• .agents/
• .notes/
• .tmp/

Desktop Helper Workflow

This repository no longer vendors a Zotero source snapshot.

The current architecture is a clean-room headless runtime with adapters around Zotero Desktop and Zotero web sync. When contributors need the optional desktop-helper path, the repo keeps a small helper workflow under desktop_helper/ rather than an in-repo upstream mirror.

That workflow is intended to:

• pin an upstream Zotero commit or tag in desktop_helper/metadata.json
• keep helper deltas as explicit patch files under desktop_helper/patches/
• build or validate against an external upstream checkout

Documentation

• docs/README.md
• USE_CASES.md
• CLI.md
• API_AND_MCP.md
• LOCAL_DESKTOP.md
• REMOTE_SYNC.md
• RECOVERY.md
• DESKTOP_HELPER.md
• ZOTERO_SOURCE_NOTES.md
• CONTRIBUTING.md

References

• Zotero Repository
• Zotero Web API Syncing
• Direct SQLite Database Access
• qmd README