Zotero MCP Server

A Model Context Protocol server that provides programmatic access to Zotero reference libraries. This server enables AI assistants to search, cite, and manage research references directly from your Zotero library.

Features

Tools

• search_items - Search and filter items in your library
• get_item - Retrieve a single item by key or DOI
• generate_citation - Generate formatted citations in multiple styles
• extract_pdf_text - Extract full-text content from PDF attachments
• create_item - Add new items to your library
• update_item - Modify existing item metadata
• delete_items - Remove items from your library
• manage_collections - Create and organize collections
• manage_tags - Add and remove tags from items

Resources

• zotero://collections - Access collection hierarchy and metadata
• zotero://tags - Browse all tags in your library
• zotero://citation-styles - List available citation styles

Prerequisites

• Node.js 20.16.0 or higher
• A Zotero account with API access
• Zotero API key from https://www.zotero.org/settings/keys

Installation

Option 1: NPM (Coming Soon)

npm install -g zotero-mcp-server

Option 2: From Source

git clone <repository-url>
cd zotero-mcp-server
npm install
npm run build

Configuration

Getting Your Credentials

1. Visit https://www.zotero.org/settings/keys
2. Create a new API key with appropriate permissions
3. Note your User ID (displayed at the top of the page)
4. Copy the generated API key

Environment Variables

Create a .env file in the project root:

ZOTERO_API_KEY=your_api_key_here
ZOTERO_USER_ID=your_user_id_here

For group libraries, use ZOTERO_GROUP_ID instead of ZOTERO_USER_ID.

Optional Configuration

ZOTERO_BASE_URL=https://api.zotero.org
ZOTERO_TIMEOUT=30000
ZOTERO_MAX_RETRIES=3
CACHE_ENABLED=true
CACHE_TTL_SECONDS=300

Usage with Claude Desktop

Add this configuration to your Claude Desktop config file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zotero": {
      "command": "node",
      "args": ["/absolute/path/to/ZoteroMCP/dist/index.js"],
      "env": {
        "ZOTERO_API_KEY": "your_api_key_here",
        "ZOTERO_USER_ID": "your_user_id_here"
      }
    }
  }
}

Restart Claude Desktop after making this change.

Tool Usage Examples

Searching Items

Search your library with various filters:

// Search by text query
{
  "query": "machine learning",
  "limit": 10
}

// Filter by item type and tags
{
  "itemType": "journalArticle",
  "tag": ["ai", "research"],
  "sort": "dateAdded",
  "direction": "desc"
}

// Search within a collection
{
  "collection": "COLLECTION_KEY",
  "limit": 25
}

Generating Citations

Create formatted citations in various styles:

{
  "itemKeys": ["ITEM_KEY_1", "ITEM_KEY_2"],
  "style": "apa"
}

// Supported styles include:
// apa, chicago-note-bibliography, mla, ieee, nature,
// science, harvard-cite-them-right, vancouver, and 10,000+ more

Extracting PDF Text

Extract text content from PDF attachments:

{
  "itemKey": "PDF_ATTACHMENT_KEY",
  "pages": {
    "start": 1,
    "end": 5
  }
}

Note: PDFs must be indexed by Zotero Desktop for full-text extraction to work.

Creating Items

Add new items to your library:

{
  "itemType": "journalArticle",
  "title": "Understanding Neural Networks",
  "creators": [
    {
      "creatorType": "author",
      "firstName": "Jane",
      "lastName": "Smith"
    }
  ],
  "date": "2024",
  "DOI": "10.1234/example",
  "tags": ["neural-networks", "deep-learning"],
  "collections": ["COLLECTION_KEY"]
}

Managing Collections

Create and organize collections:

// List all collections
{
  "action": "list"
}

// Create a new collection
{
  "action": "create",
  "name": "Machine Learning Papers"
}

// Create a nested collection
{
  "action": "create",
  "name": "Deep Learning",
  "parentCollection": "PARENT_COLLECTION_KEY"
}

Managing Tags

Add or remove tags from items:

// Add tags to an item
{
  "action": "add_to_item",
  "itemKey": "ITEM_KEY",
  "tags": ["ai", "research"]
}

// Remove tags from an item
{
  "action": "remove_from_item",
  "itemKey": "ITEM_KEY",
  "tag": "outdated"
}

// List all tags
{
  "action": "list"
}

Resource Usage Examples

Collections Resource

zotero://collections

Returns all collections with hierarchy information, item counts, and metadata.

zotero://collections/COLLECTION_KEY

Returns details for a specific collection.

Tags Resource

zotero://tags

Returns all tags in your library with usage counts.

Citation Styles Resource

zotero://citation-styles

Returns a list of commonly used citation styles with their identifiers.

API Details

Rate Limiting

The server implements automatic rate limiting with exponential backoff:

• Initial retry delay: 5 seconds
• Maximum retries: 3 (configurable)
• Respects Zotero API Backoff and Retry-After headers
• Requests are queued during rate limit periods

Caching

Intelligent caching reduces API calls and improves performance:

• Item templates: 1 hour
• Collections and tags: 15 minutes
• Search results: 5 minutes
• PDF full-text: 30 days
• Citations: 1 hour

Error Handling

All errors are transformed into descriptive messages:

• 400 - Invalid request parameters
• 401/403 - Authentication failure (check API key)
• 404 - Item or resource not found
• 409 - Version conflict (item modified elsewhere)
• 412 - Precondition failed (library version changed)
• 429 - Rate limited (automatic retry)
• 5xx - Server error (automatic retry)

Development

Building from Source

npm install
npm run build

Running in Development Mode

npm run dev

Project Structure

src/
├── index.ts              # Server entry point
├── config/
│   └── default.ts        # Configuration management
├── services/
│   ├── zotero-client.ts  # Zotero API client
│   ├── cache-manager.ts  # Caching layer
│   └── pdf-extractor.ts  # PDF text extraction
├── tools/
│   └── index.ts          # MCP tool implementations
├── resources/
│   └── index.ts          # MCP resource implementations
├── utils/
│   ├── validators.ts     # Input validation
│   └── error-handler.ts  # Error transformation
└── types/
    └── zotero.ts         # Type definitions

Troubleshooting

Server won't start

Ensure you have created a .env file with valid credentials:

cp .env.example .env
# Edit .env and add your ZOTERO_API_KEY and ZOTERO_USER_ID

Authentication errors

• Verify your API key at https://www.zotero.org/settings/keys
• Ensure the API key has appropriate read/write permissions
• Check that ZOTERO_USER_ID matches the ID shown on the API keys page

PDF extraction fails

• PDFs must be indexed by Zotero Desktop application
• Open Zotero Desktop and allow it to index PDF attachments
• Verify the item has an actual PDF attachment (not just a link)

Claude Desktop doesn't show Zotero tools

• Verify the absolute path in claude_desktop_config.json is correct
• Check that environment variables in the config are set
• Restart Claude Desktop completely (quit and reopen)
• Check Claude Desktop logs: Help → View Logs

License

MIT

Contributing

Contributions are welcome. Please open an issue or submit a pull request.

Attribution

This MCP server uses the Zotero Web API to provide programmatic access to Zotero libraries. Zotero is a free, open-source reference management software developed by the Corporation for Digital Scholarship.

This project is not affiliated with, endorsed by, or sponsored by Zotero or the Corporation for Digital Scholarship.

Links

• Zotero
• Zotero API Documentation
• Model Context Protocol
• Zotero API Keys