Kimi Zotero Plugin

A Kimi plugin for managing your Zotero library with full read and write access. Search, organize, edit, and export references, collections, notes, tags, and attachments through the Zotero Web API v3.

---

Features

• 🔍 Advanced search — Search by title, author, content, tags, collections
• 📁 Collection management — Create, rename, delete, and organize hierarchical collections
• 📝 Full item CRUD — Create, read, update, and delete references of any type
• 📎 Notes & tags — Add HTML notes and manage tags on any item
• 📤 Citation export — Export citations and bibliographies in BibTeX, RIS, CSL JSON, and more
• 📄 File attachments — Upload PDFs and other files using Zotero's official two-step protocol
• 👥 Group libraries — Support for both personal and group Zotero libraries

---

Prerequisites

Before installing, you need:

1. Kimi Desktop installed on your computer
2. A Zotero API key with read and write permissions
3. Your Zotero User ID

How to get your Zotero API key

1. Go to https://www.zotero.org/settings/keys
2. Sign in to your Zotero account
3. Click "Create new private key"
4. Enable these permissions:
   • ✅ Allow library access
   • ✅ Allow write access
   • ✅ Allow notes access
   • ✅ Allow file access
5. Copy the generated API key (a long string like AbC123XyZ...)
6. Your User ID is shown on the same page, below your username

---

Installation

Step 1: Extract the archive

Clone this repository to any folder on your computer.

git clone https://github.com/FlacH7/kimi-zotero-plugin.git

This creates a kimi-zotero-plugin/ folder.

Step 2: Register the plugin in your personal marketplace

Path A:

In a Kimi conversation, just ask:

"Register this local plugin in my personal market: <absolute path to this repo>"

The agent validates and registers it. Then open Kimi's Plugins page → 「个人」 (Personal) tab → click ＋ on "Kimi-zotero-plugin". No restart needed.

Path B (If path A doesn't works):

Open a terminal and run the appropriate command for your OS:

Windows:

# Find your share directory
$share = "$env:APPDATA\kimi-desktop\daimon-share"

# If kimi-daimon is in your PATH
kimi-daimon kimi-plugin register-personal "C:\full\path\to\kimi-zotero-plugin" --share-dir "$share"

# If not, use the full path to the executable
& "$env:APPDATA\kimi-desktop\daimon-bundle\bin\kimi-daimon.cmd" kimi-plugin register-personal "C:\full\path\to\kimi-zotero-plugin" --share-dir "$share"

macOS:

kimi-daimon kimi-plugin register-personal ~/path/to/kimi-zotero-plugin \
  --share-dir ~/Library/Application\ Support/kimi-desktop/daimon-share

Linux:

kimi-daimon kimi-plugin register-personal ~/path/to/kimi-zotero-plugin \
  --share-dir ~/.kimi/daimon-share

Note: If kimi-daimon is not in your PATH, find it in your Kimi Desktop installation folder (typically kimi-desktop/daimon-bundle/bin/).

Step 3: Install from Kimi Desktop

1. Open Kimi Desktop
2. Go to the Plugins panel (插件)
3. Switch to the 「个人」 (Personal) tab
4. Find "Kimi Zotero"
5. Click the ＋ or 「安装」 (Install) button
6. Done! The plugin activates immediately — no restart needed

---

API Key Configuration

Once the plugin is installed, you need to provide your API key and User ID. There are two ways to do this:

Option A: Environment variables (recommended for regular use)

Set these environment variables on your system:

• ZOTERO_API_KEY = your API key
• ZOTERO_USER_ID = your User ID

Windows (PowerShell):

[Environment]::SetEnvironmentVariable("ZOTERO_API_KEY", "YOUR_API_KEY_HERE", "User")
[Environment]::SetEnvironmentVariable("ZOTERO_USER_ID", "YOUR_USER_ID_HERE", "User")

macOS/Linux (bash/zsh):

echo 'export ZOTERO_API_KEY="YOUR_API_KEY_HERE"' >> ~/.bashrc
echo 'export ZOTERO_USER_ID="YOUR_USER_ID_HERE"' >> ~/.bashrc
source ~/.bashrc

Option B: Pass on each command

If you don't set environment variables, simply tell Kimi your API key when you want to use the plugin. Kimi will pass it as --api-key and --user-id arguments.

Security: Never hardcode your API key into plugin files. The client receives it as an argument or environment variable.

---

Usage

Once installed and configured, just tell Kimi in natural language what you want to do:

Request	Action
"Search my Zotero for papers on machine learning"	Search your library
"List my Zotero collections"	Show all collections
"Create a collection called 'Thesis'"	New collection
"Export references ABC123 and DEF456 in BibTeX"	Export bibliography
"Add a note to paper XYZ789"	Create linked note
"Tag paper ABC as 'important'"	Add tags

You can also use slash commands:

• /zotero search machine learning
• /zotero recent
• /zotero collections

---

Architecture

kimi-zotero-plugin/
├── kimi.plugin.json           # Plugin manifest
├── scripts/
│   └── zotero_client.py       # Zotero Web API v3 client (CRUD + export + upload)
├── skills/
│   └── kimi-zotero-plugin/
│       └── SKILL.md           # Agent instructions & command reference
└── commands/
    └── kimi-zotero-plugin.md         # Slash command definitions

zotero_client.py — Command Reference

# Authentication
python3 scripts/zotero_client.py auth test --api-key <KEY> --user-id <ID>

# Collections
python3 scripts/zotero_client.py collections list
python3 scripts/zotero_client.py collections create --name "New Collection"
python3 scripts/zotero_client.py collections update --key <KEY> --name "New Name" --version <VER>
python3 scripts/zotero_client.py collections delete --key <KEY>

# Items
python3 scripts/zotero_client.py items list [--collection <KEY>]
python3 scripts/zotero_client.py items search --query "machine learning"
python3 scripts/zotero_client.py items create --data '{"itemType":"book","title":"..."}'
python3 scripts/zotero_client.py items update --key <KEY> --data '{...}' --version <VER>
python3 scripts/zotero_client.py items delete --key <KEY>

# Notes
python3 scripts/zotero_client.py notes create --content "<p>Note</p>" --parent <ITEM_KEY>

# Tags
python3 scripts/zotero_client.py tags list
python3 scripts/zotero_client.py tags add --key <ITEM_KEY> --tags tag1 tag2

# Export
python3 scripts/zotero_client.py export item --key <KEY> --format bib
python3 scripts/zotero_client.py export bibliography --keys "K1,K2" --format bib

# Templates
python3 scripts/zotero_client.py template get --item-type journalArticle

All commands support --api-key, --user-id, and optional --group-id.

---

Troubleshooting

"kimi-daimon is not recognized as a command"

Find the executable in your Kimi Desktop installation:

• Windows: C:\Users\<USER>\AppData\Roaming\kimi-desktop\daimon-bundle\bin\kimi-daimon.cmd
• macOS: ~/Library/Application Support/kimi-desktop/daimon-bundle/bin/kimi-daimon
• Linux: ~/.kimi/daimon-bundle/bin/kimi-daimon

"Plugin doesn't appear in the 个人 tab"

Make sure:

1. The register-personal command completed without errors
2. The kimi-zotero-plugin/ folder contains kimi.plugin.json
3. Refresh the Plugins page (close and reopen)

"Error 401 Unauthorized"

Your API key is incorrect or lacks write permissions. Generate a new one at zotero.org/settings/keys with all permissions enabled.

"Error 412 Precondition Failed"

Zotero uses optimistic versioning. The item was modified elsewhere between your read and write. Fetch the item again and retry with the latest version.

---

Changelog

v0.1.0

• Full CRUD for collections, items, notes, and tags
• Citation export in BibTeX, RIS, CSL JSON
• File attachment upload via Zotero's two-step protocol
• Group library support
• Slash commands (/zotero)

---

License

MIT

---

Version: 0.1.0+local
Compatible with: Zotero Web API v3