Zotero MCP Server
A Model Context Protocol (MCP) server that provides comprehensive access to your Zotero research library. Give LLMs full context about your papers, including metadata, abstracts, notes, annotations, and full-text PDF content.
Features
- 🔍 Full Library Search: Search items by title, author, tags, or full-text content
- 📚 Complete Metadata: Access all item fields, creators, tags, and collections
- 📄 Full-Text Access: Extract and search PDF content
- ✏️ Annotations & Notes: Access PDF highlights, comments, and user notes
- 📖 Citations: Generate formatted bibliographies in various styles (APA, MLA, Chicago, etc.)
- 🔄 Dual Backend: Switch between Web API (remote) and local SQLite database
Quick Start
Prerequisites
- Node.js >= 18.0.0
- A Zotero account with API key (Web API mode only — not needed for local mode)
Check if Node.js is installed:```bash
node -v
If not installed or version is below 18, download from nodejs.org (LTS recommended) or use a version manager:```bash
# Windows (winget)
winget install OpenJS.NodeJS.LTS
# macOS (Homebrew)
brew install node
# Linux (apt)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
Installation```bash
Clone the repository
git clone https://github.com/drxaibi/zotero-mcp.git
cd zotero-mcp
Install dependencies
npm install
Build the project
npm run build
### Get Your Zotero API Key
1. Go to Zotero API Keys
2. Create a new key with these permissions:
- ✅ Allow library access
- ✅ Allow notes access
- ❌ Allow write access (not needed)
3. Note your **User ID** shown at the top of the keys page
4. Copy the generated API key
### Configuration
Choose your AI assistant and follow the setup instructions:
---
### MCP Configuration
Add the following configuration to your MCP client. Replace the path with your actual `zotero-mcp` location:```jsonc
{
"mcpServers": {
"zotero": {
"command": "node",
"args": ["C:/path/to/zotero-mcp/dist/index.js"],
"env": {
// Web API mode (default)
"ZOTERO_API_KEY": "your-api-key-here",
"ZOTERO_USER_ID": "your-user-id-here"
// Local mode (uncomment below, comment out API_KEY and USER_ID above)
// "ZOTERO_MODE": "local",
// "ZOTERO_DATA_DIR": "" // Leave empty for auto-detection, or set your path
}
}
}
}
> Path format: Use forward slashes (/) or escaped backslashes (\\). Always use absolute paths.
> Local mode: Close Zotero app before using (SQLite file locking).
Note for VS Code + Copilot: Use "servers" instead of "mcpServers" as the root key:```jsonc
{
"servers": {
"zotero": {
"command": "node",
"args": ["C:/path/to/zotero-mcp/dist/index.js"],
"env": {
// Web API mode (default)
"ZOTERO_API_KEY": "your-api-key-here",
"ZOTERO_USER_ID": "your-user-id-here"
// Local mode (uncomment below, comment out API_KEY and USER_ID above)
// "ZOTERO_MODE": "local",
// "ZOTERO_DATA_DIR": "" // Leave empty for auto-detection, or set your path
}
}
}
}
### Where to Add Configuration
Client · Config File Location · Root Key
**Claude Desktop** · Windows: `%APPDATA%\Claude\claude_desktop_config.json`
macOS: `~/Library/Application Support/Claude/claude_desktop_config.json` · `mcpServers`
**VS Code + Copilot** · `.vscode/mcp.json` in workspace · `servers`
**VS Code + Claude** · `.vscode/mcp.json` in workspace · `mcpServers`
**Claude Code (CLI)** · Windows: `%USERPROFILE%\.claude\settings.json`
macOS/Linux: `~/.claude/settings.json` · `mcpServers`
**Cursor** · `.cursor/mcp.json` in workspace
or Settings → Features → MCP Servers · `mcpServers`
After adding configuration, restart your client to load the server.
---
### Configuration Options
| Setting | Default | Description |
|---------|---------|-------------|
| `ZOTERO_API_KEY` | *required* | Your Zotero API key |
| `ZOTERO_USER_ID` | *required* | Your Zotero user ID |
| `ZOTERO_MODE` | `web` | `web` (API) or `local` (SQLite) |
| `ZOTERO_GROUP_ID` | *empty* | Group library ID (if accessing group instead of personal) |
| `ZOTERO_DEFAULT_LIMIT` | `25` | Results per query (1-100) |
| `ZOTERO_CACHE_TTL` | `300` | Cache duration in seconds |
| `ZOTERO_MAX_FULLTEXT_LENGTH` | `100000` | Max characters for full-text extraction |
| `ZOTERO_DATA_DIR` | *auto-detected* | Path to Zotero data folder (local mode only) |
| `ZOTERO_CACHE_ENABLED` | `true` | Enable/disable response caching |
| `ZOTERO_EXTRACT_PDF` | `true` | Enable PDF text extraction |
**Full configuration with all options:**```jsonc
{
"mcpServers": {
"zotero": {
"command": "node",
"args": ["C:/path/to/zotero-mcp/dist/index.js"],
"env": {
// Required for Web API mode
"ZOTERO_API_KEY": "your-api-key-here",
"ZOTERO_USER_ID": "your-user-id-here",
// Optional settings
"ZOTERO_MODE": "web",
"ZOTERO_GROUP_ID": "",
"ZOTERO_DEFAULT_LIMIT": "25",
"ZOTERO_CACHE_ENABLED": "true",
"ZOTERO_CACHE_TTL": "300",
"ZOTERO_EXTRACT_PDF": "true",
"ZOTERO_MAX_FULLTEXT_LENGTH": "100000"
// Local mode (uncomment and comment out API_KEY/USER_ID above)
// "ZOTERO_MODE": "local",
// "ZOTERO_DATA_DIR": "" // Leave empty for auto-detection, or set your path
}
}
}
}
Local mode notes:
- No API key needed - just set ZOTERO_MODE to local
- Zotero app must be closed when using local mode (SQLite file locking)
Finding your Zotero data directory:
- Open Zotero app
- Go to Edit → Settings (Windows/Linux) or Zotero → Settings (macOS)
- Click Advanced → Files and Folders
- Look for Data Directory Location — copy this path
Auto-detection: Leave ZOTERO_DATA_DIR empty ("") or omit it entirely. The server will automatically look for:
- Windows: C:\Users\\Zotero
- macOS: /Users//Zotero
- Linux: /home//Zotero
If auto-detection fails, set the exact path from Zotero settings:```jsonc
"ZOTERO_DATA_DIR": "C:/Users/John/Zotero" // Use YOUR actual path
## Available Tools
| Tool | Description |
|------|-------------|
| `search_library` | Search items by query, tags, type, or collection |
| `get_item` | Get complete item details with all metadata |
| `get_item_fulltext` | Extract full text from PDFs |
| `get_item_notes` | Get all notes attached to an item |
| `get_item_annotations` | Get PDF highlights and comments |
| `list_collections` | List all collections |
| `get_collection_items` | Get items in a collection |
| `list_tags` | List all tags with counts |
| `search_fulltext` | Search across all PDF content |
| `get_bibliography` | Generate formatted citations |
| `get_related_items` | Find related items |
| `get_recent_items` | Get recently added/modified items |
## Available Resources
| Resource | Description |
|----------|-------------|
| `zotero://library/stats` | Library statistics overview |
| `zotero://collections` | Full collection hierarchy |
| `zotero://tags` | All tags with item counts |
| `zotero://recent` | Recently modified items |
| `zotero://schema/item-types` | Supported item types |
## Example Prompts
Once connected, you can ask Claude things like:
- *"Search my Zotero library for papers about machine learning"*
- *"Get the full text of the paper with key ABC123"*
- *"What annotations did I make on this paper?"*
- *"Show me all papers in my 'Literature Review' collection"*
- *"Find papers tagged with 'methodology'"*
- *"Generate APA citations for these three papers"*
- *"What papers did I add this week?"*
- *"Summarize the key findings from my climate change papers"*
## Architecture```
┌─────────────────────────────────────────────────────────────┐
│ MCP Server (index.ts) │
├─────────────────────────────────────────────────────────────┤
│ Tools │ Resources │
│ - search_library │ - zotero://library/stats │
│ - get_item │ - zotero://collections │
│ - get_fulltext │ - zotero://tags │
│ - ... │ - ... │
├─────────────────────┴───────────────────────────────────────┤
│ Backend Interface │
├─────────────────────────────────────────────────────────────┤
│ Web API Backend │ Local SQLite Backend │
│ (api.zotero.org) │ (zotero.sqlite) │
└─────────────────────────────────────────────────────────────┘
Troubleshooting
"ZOTERO_API_KEY is required"
Make sure you've set the environment variables in your MCP configuration.
"Could not detect Zotero data directory"
In local mode, set ZOTERO_DATA_DIR to your Zotero data folder path explicitly.
"Database is locked" (Local mode)
Close Zotero before using local mode. Zotero locks the SQLite database while running.
No full-text results
Make sure Zotero has indexed your PDFs. In Zotero: Edit → Preferences → Search → Rebuild Index.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Citation
If you use this project in your research or work, please cite it:bibtex
@software{zotero_mcp_2026,
author = {drxaibi},
title = {Zotero MCP Server: Model Context Protocol Server for Zotero},
year = {2026},
url = {https://github.com/drxaibi/zotero-mcp},
note = {A Model Context Protocol server providing LLM access to Zotero research libraries}
}
Or in text format:
> drxaibi. (2026). Zotero MCP Server: Model Context Protocol Server for Zotero. GitHub. https://github.com/drxaibi/zotero-mcp
License
This project is licensed under the MIT License - see the LICENSE file for details.
Acknowledgments
- Zotero - The amazing open-source reference manager
- Model Context Protocol - The protocol that makes this possible
- Anthropic - For Claude and the MCP SDK
Related Projects
- Zotero - The Zotero client
- pyzotero - Python client for Zotero API
- MCP Servers - Official MCP server examples
