Using Claude Code with Zotero (2026)

Last updated: April 21, 2026

Zotero’s Chrome connector transforms your browser into a powerful research assistant, automatically detecting and saving academic papers, web articles, and citations as you browse. For developers and power users, the extension offers granular control over metadata extraction, storage behavior, and integration with local Zotero installations. This guide covers the complete setup process, configuration options, and practical troubleshooting strategies.

How Claude Code Supercharges Zotero Research Workflows

The combination of Zotero for paper collection and Claude Code for paper processing creates a powerful academic development workflow. Once you have collected papers via the Zotero Chrome connector, Claude Code can:

Summarize collected papers by reading PDFs from your Zotero storage directory and generating concise technical summaries
Implement paper algorithms directly from research papers you have saved, translating pseudocode into working implementations
Generate literature review sections by analyzing metadata and abstracts across your Zotero collections
Extract and organize citations for documentation and README files in your codebases
Compare methodologies across multiple papers in the same Zotero collection

A typical workflow: collect 10-15 papers on a topic using Zotero’s Chrome connector, then use Claude Code to read the PDFs, synthesize the key findings, and generate implementation code based on the most promising approaches.

Related Claude Code guides:

Claude Code PDF Processing and Analysis
Claude Code Research Automation
Claude Code Documentation Generation

Prerequisites and Initial Installation

Before installing the Chrome connector, ensure you have:

Zotero desktop application (version 6.0 or later) installed on your machine
Google Chrome, Chromium-based browser (Brave, Edge, or Firefox with Zotero Add-on)
Connector enabled in your Zotero preferences

Install the extension from the Chrome Web Store or download directly from Zotero’s website. After installation, the connector appears as a toolbar icon in Chrome.

Configuring the Connector for Your Workflow

The Chrome connector works by detecting metadata on web pages and sending it to your local Zotero desktop application via a local server. Open Zotero, navigate to Edit → Preferences → Connector to access configuration options.

Setting Up Automatic Capture

The default behavior captures bibliographic metadata automatically when the connector detects a recognized item type. For more control:

// Configure via Zotero's config editor
// Type about:config in Zotero's address bar
// Set extensions.zotero.connector.server.port to custom port

Key preferences to adjust:

Automatic Snapshot: Enable to capture page snapshots automatically
Proxy Autodetection: Let Zotero handle proxy configurations
Ignored Sites: Add domains where the connector should remain inactive

Manual Item Saving

When automatic detection fails, use the toolbar icon to manually save items. Click the Zotero icon in Chrome’s toolbar, the icon’s badge indicates detected items. For complex pages with multiple references, use the “Save to Zotero” button within specific academic databases.

Advanced Configuration for Developers

If you need programmatic control or custom integrations, the connector exposes several developer-facing options.

Using the Connector API

The Chrome connector communicates via HTTP to your local Zotero instance. The server runs on localhost with a configurable port (default: 23119). You can interact directly:

Test connector availability
curl http://localhost:23119/allowed
Response: {"version":6,"host":"MacOSX","sdk":false}

Custom Metadata Selectors

For sites not automatically recognized, create custom translators or use the connector’s manual entry form. The metadata form accepts:

Title, Authors, Publication
DOI, ISBN, or URL
Tags and Collections
Notes and attachments

Debugging Connector Issues

When the connector fails to communicate with Zotero:

Check that Zotero is running. the connector requires the desktop app active
Verify the server port matches between Chrome and Zotero preferences
Disable conflicting extensions. some privacy extensions block local HTTP requests
Clear browser cache. cached redirects sometimes interfere

// Check connector status in browser console
// Open DevTools (F12), type:
zoteroConnectorStatus

This returns an object with connection state, detected items, and error messages.

Integration with Reference Management

The Chrome connector becomes powerful when combined with Zotero’s ecosystem.

Syncing to Online Library

Enable sync in Zotero to automatically upload items to your online library. Configure sync settings in Edit → Preferences → Sync:

Sync settings structure
- Automatic sync: enabled
- Sync full-text content: enabled (for supported PDFs)
- File sync: enabled

Your captured research then becomes accessible across devices through zotero.org.

Connecting with Third-Party Tools

Many research workflows benefit from integrations:

Zoterobib: Generate quick bibliographies without full Zotero installation
Citation managers: Export to BibTeX, RIS, or CSL JSON
Writing tools: Plugins for Obsidian, VS Code, and LaTeX editors

Common Issues and Solutions

Connector Icon Grayed Out

This indicates the desktop app isn’t running or the server failed to start. Launch Zotero and wait 10 seconds. If persistent, reset the connector:

Reset connector on macOS
rm -rf ~/Library/Application\ Support/Zotero/connectors/
Restart Zotero and Chrome

Metadata Missing or Incorrect

When captured metadata lacks required fields:

Manually edit the item in Zotero after saving
Use the “Retrieve Metadata” function to fetch from databases
Install additional translators for specific publishers

Proxy and Network Issues

Corporate networks may require proxy configuration. Set proxy rules in Zotero preferences or use the connector’s manual proxy detection override.

Writing Custom Translators

When Zotero doesn’t recognize a site automatically, the correct fix is a custom translator. not a manual workaround. Translators are JavaScript files that tell Zotero how to detect and extract metadata from a specific domain. You write one once; it works every time thereafter.

Translators live in your Zotero data directory under translators/. Create a new .js file with the required header comment:

{
 "translatorID": "your-uuid-here",
 "label": "My Research Portal",
 "creator": "Your Name",
 "target": "^https?://research\\.example\\.com/",
 "minVersion": "5.0",
 "maxVersion": "",
 "priority": 100,
 "inRepository": false,
 "translatorType": 4,
 "browserSupport": "gcsibv",
 "lastUpdated": "2026-03-01 00:00:00"
}

The target field is a regex matched against the page URL. translatorType: 4 means web translator. Then implement the two required functions:

function detectWeb(doc, url) {
 // Return item type if page looks like a saveable item
 if (doc.querySelector('meta[name="citation_doi"]')) {
 return 'journalArticle';
 }
 return false;
}
function doWeb(doc, url) {
 const item = new Zotero.Item('journalArticle');
 item.title = doc.querySelector('meta[name="citation_title"]')?.content;
 item.DOI = doc.querySelector('meta[name="citation_doi"]')?.content;
 const authors = doc.querySelectorAll('meta[name="citation_author"]');
 authors.forEach(a => {
 const parts = a.content.split(', ');
 item.creators.push({
 lastName: parts[0],
 firstName: parts[1] || '',
 creatorType: 'author'
 });
 });
 item.complete();
}

Most academic publisher sites use citation_* meta tags (a Google Scholar convention), so this pattern covers a wide range of portals. Test by loading your target URL, right-clicking anywhere on the page, and choosing “Save to Zotero”. if your translator fires, the icon in Chrome’s toolbar will change to match the item type.

Bulk Import and Folder Organization

Zotero’s connector saves one item at a time from the browser, but your library management benefits from systematic organization from the start. Set up collections before you start a research project, then use the connector’s collection selector to route items directly on save.

The keyboard shortcut for saving with collection selection is to hold Shift while clicking the toolbar icon. This opens the item creation dialog with a collection picker, rather than dumping everything into “My Library.”

For bulk import from external sources, Zotero handles several formats directly. From a DOI list in a text file:

Each DOI on its own line, then File → Import in Zotero
1093/mnras/staa123
1016/j.cell.2025.01.042
1038/s41586-025-07892-3

Paste the DOI list into Zotero’s “Add Item by Identifier” dialog (the magic wand icon) by clicking the icon and pasting multiple DOIs separated by spaces or newlines. Zotero fetches metadata for all of them in sequence.

For RIS or BibTeX files exported from another manager, use File → Import and select the file. Zotero preserves tags and notes from most export formats.

Using the Zotero Web API for Custom Tooling

The Zotero API gives programmatic access to your library without the connector. This is the right path when you want to build a reading pipeline, automate tag assignment, or pull citations into a custom writing environment.

First, generate an API key at zotero.org/settings/keys. Set appropriate permissions. read-only for most tooling, read/write if you need to add or modify items.

Get all items in your library
curl -H "Zotero-API-Key: YOUR_KEY" \
 "https://api.zotero.org/users/YOUR_USER_ID/items?format=json&limit=25"

The API returns JSON arrays of item objects. Each object follows the same schema as what the connector creates locally:

{
 "key": "ABC12DEF",
 "version": 42,
 "itemType": "journalArticle",
 "title": "Deep Learning for Citation Extraction",
 "creators": [{"creatorType": "author", "firstName": "Jane", "lastName": "Smith"}],
 "DOI": "10.1000/xyz123",
 "tags": [{"tag": "machine-learning"}, {"tag": "NLP"}]
}

To add items via API (useful for automated literature monitoring scripts):

curl -X POST \
 -H "Zotero-API-Key: YOUR_KEY" \
 -H "Content-Type: application/json" \
 "https://api.zotero.org/users/YOUR_USER_ID/items" \
 -d '[{"itemType":"journalArticle","title":"New Paper","DOI":"10.1234/example"}]'

Rate limits are 100 requests per 30 seconds for write operations, 5 requests per second for reads. For bulk operations, build in a 200ms delay between calls.

Integrating Zotero with Obsidian and VS Code

Two integrations that substantially improve research workflows for developers and writers.

Obsidian via Zotero Integration plugin: Install the “Zotero Integration” plugin from Obsidian’s community plugins. Configure it to point at your Zotero data directory. Once set up, you can import a citation from your Zotero library directly into an Obsidian note with a single command:

{{citekey}}. {{title}} ({{year}})
Authors: {{authors}}
DOI: {{DOI}}

Define your own template in the plugin settings. Common fields: citekey, title, authors, year, abstract, tags, collections. The plugin generates a note per paper with the template filled in, plus a link back to the PDF attachment in Zotero.

VS Code via Citation Picker: Install the “Zotero Citation Picker” extension for VS Code. It connects to the same local server port (23119) that the Chrome connector uses. With your Zotero desktop app running, press the configured hotkey in VS Code (default Alt+Z) to open a fuzzy-search picker over your entire library. Selecting an item inserts a formatted citation at the cursor. useful when writing technical documentation or research notes in Markdown.

Both integrations require the Zotero desktop app to be running. If you close Zotero, the local server goes down and both tools show connection errors until you relaunch.

Maintaining Translator Health Over Time

Academic publisher sites change their HTML without warning. A translator that worked last month may silently fail after a site redesign. Two practices keep your setup reliable.

First, subscribe to Zotero’s automatic translator updates. In Edit → Preferences → Advanced → Files and Folders, the default data directory includes a translators folder. Zotero checks for translator updates from its GitHub repository on each startup. leave this enabled.

Second, when a site stops working, check the Zotero forum before writing a custom translator from scratch. Most major publishers have existing translators maintained by the community. Search for the publisher name at forums.zotero.org. If a translator exists but is broken, the fix is usually a single CSS selector update, not a full rewrite.

For sites you’ve written your own translators for, version-control them. Keep a zotero-translators/ directory in your dotfiles or a private repo. After any Zotero major version update, reload your translators by restarting the app and verifying the target sites still save correctly.

Automation Possibilities

For developers interested in extending functionality, several options exist:

Bookmarklets: Create custom save triggers for specific workflows
Chrome Extension APIs: Use chrome.storage for per-instance settings
Zotero API: Programmatic access to your library for custom tooling

A practical automation worth building: a script that polls your Zotero library for items tagged “to-read”, fetches their abstracts via the API, and sends a digest to your email or messaging app on a schedule. This closes the loop between capturing research and actually reading it. the gap where most Zotero libraries become graveyards of saved-but-never-read papers.

This enables automated literature reviews, research notifications, and custom citation generation pipelines.

Try it: Paste your error into our Error Diagnostic for an instant fix.

This took me 3 hours to figure out. I put it in a CLAUDE.md so I'd never figure it out again. Now Claude gets it right on the first try, every project. 16 framework templates. Next.js, FastAPI, Laravel, Rails, Go, Rust, Terraform, and 9 more. Each one 300+ lines of "here's exactly how this stack works." Copy into your project. Done. **[See the templates →](https://zovo.one/lifetime?utm_source=ccg&utm_medium=cta-config&utm_campaign=zotero-chrome-extension-setup-guide)** $99 once. Yours forever. I keep adding templates monthly.