mcp-zotero

This MCP server provides a Zotero-integrated toolset for use with language models. It exposes 15 tools that let an LLM browse your Zotero library, add items (including by DOI), attach PDFs, read full-text, and inject live Zotero citations into Word documents. Tools cover library navigation (get_collections, get_collection_items, get_items_details, get_item_fulltext), content addition (add_items_by_doi, add_items, create_collection, import_pdf_to_zotero, find_and_attach_pdfs, add_linked_url_attachment), deletion (delete_items, delete_collection), and citation/document handling (inject_citations, get_user_id). The server is designed to be self-documenting through its tool listings, enabling an LLM with or without local filesystem access to work with Zotero data depending on capabilities.

To get started, configure your Zotero API credentials and environment variables as described in the installation guide, then run the MCP server. When connected, the MCP will present each available tool with usage guidance and cross-references, so an LLM can discover workflows such as adding papers by DOI, locating metadata, fetching PDFs, and injecting Zotero citations into documents. For Claude users, there is an optional Claude skill for in-sandbox citation injection that does not require local file access.

Prerequisites:

• Node.js and npm (for npx usage) or an environment that can run npx commands
• A Zotero API key with library read/write and file access permissions
• Your Zotero user ID
• Optional: Unpaywall account email for OA PDF lookup

Steps:

1. Obtain Zotero API credentials:
   • Create an API key at https://www.zotero.org/settings/keys (enable library read/write and file access)
   • Retrieve your user ID: curl -H "Zotero-API-Key: YOUR_API_KEY" https://api.zotero.org/keys/current
2. Set environment variables (replace placeholders):
   • export ZOTERO_API_KEY="your-api-key"
   • export ZOTERO_USER_ID="your-user-id"
   • export UNPAYWALL_EMAIL="your@email.edu" # Optional
   • export UNSAFE_OPERATIONS="none" # Optional: none | items | all
3. Install and run the MCP Zotero server using npx (no local install needed):
   • npx -y @xevos117/mcp-zotero
   • The server will start and listen for MCP connections with the configured environment.
4. Alternative: use Claude integration examples (if you’re wiring Claude Desktop or Claude Code) as described in the README to connect the MCP server to your Claude projects.

Notes and tips:

• By default, destructive actions are blocked. Set UNSAFE_OPERATIONS to items or all to enable deletions, with all-related safety warnings in mind.
• UNPAYWALL_EMAIL enables automatic OA PDF lookup when using add_items_by_doi and find_and_attach_pdfs; omit if not desired.
• The integration supports Claude Skill for in-sandbox citation injection, useful for LLMs without local file access.
• If you encounter API rate limits, consider using UNPAYWALL_EMAIL or adjusting requests flow via the tool parameters in your calls.
• The provided configuration example demonstrates how to embed credentials directly in the mcpServers configuration for Claude integrations; adapt as needed for your deployment security practices.