[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-72359":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":17,"stars7d":18,"stars30d":19,"stars90d":16,"forks30d":16,"starsTrendScore":20,"compositeScore":21,"rankGlobal":10,"rankLanguage":10,"license":22,"archived":23,"fork":23,"defaultBranch":24,"hasWiki":25,"hasPages":25,"topics":26,"createdAt":10,"pushedAt":10,"updatedAt":31,"readmeContent":32,"aiSummary":33,"trendingCount":16,"starSnapshotCount":16,"syncStatus":34,"lastSyncTime":35,"discoverSource":36},72359,"zotero-mcp","54yyyu\u002Fzotero-mcp","54yyyu","Zotero MCP: Connects your Zotero research library with Claude and other AI assistants via the Model Context Protocol to discuss papers, get summaries, analyze citations, and more.","https:\u002F\u002Fstevenyuyy.com\u002Fzotero-mcp\u002F",null,"Python",3732,329,10,84,0,98,231,681,294,29.56,"MIT License",false,"main",true,[27,28,29,30],"claude","mcp","semantic-search","zotero","2026-06-12 02:03:02","# Zotero MCP: Chat with your Research Library—Local or Web—in Claude, ChatGPT, and more.\n\n\u003Cp align=\"center\">\n  \u003Ca href=\"https:\u002F\u002Fwww.zotero.org\u002F\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FZotero-CC2936?style=for-the-badge&logo=zotero&logoColor=white\" alt=\"Zotero\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fwww.anthropic.com\u002Fclaude\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FClaude-6849C3?style=for-the-badge&logo=anthropic&logoColor=white\" alt=\"Claude\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fchatgpt.com\u002F\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FChatGPT-74AA9C?style=for-the-badge&logo=openai&logoColor=white\" alt=\"ChatGPT\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FMCP-0175C2?style=for-the-badge&logoColor=white\" alt=\"MCP\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fpypi.org\u002Fproject\u002Fzotero-mcp-server\u002F\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fpypi\u002Fv\u002Fzotero-mcp-server?style=for-the-badge&logo=pypi&logoColor=white\" alt=\"PyPI\">\n  \u003C\u002Fa>\n  \u003Ca href=\"https:\u002F\u002Fdiscord.gg\u002FBvgjbcBUqg\">\n    \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-5865F2?style=for-the-badge&logo=discord&logoColor=white\" alt=\"Discord\">\n  \u003C\u002Fa>\n\u003C\u002Fp>\n\n**Zotero MCP** seamlessly connects your [Zotero](https:\u002F\u002Fwww.zotero.org\u002F) research library with [ChatGPT](https:\u002F\u002Fopenai.com), [Claude](https:\u002F\u002Fwww.anthropic.com\u002Fclaude), and other AI assistants (e.g., [Cherry Studio](https:\u002F\u002Fcherry-ai.com\u002F), [Chorus](https:\u002F\u002Fchorus.sh), [Cursor](https:\u002F\u002Fwww.cursor.com\u002F)) via the [Model Context Protocol](https:\u002F\u002Fmodelcontextprotocol.io\u002Fintroduction). Review papers, get summaries, analyze citations, extract PDF annotations, and more!\n\n---\n\n## ✨ Features\n\n### 🧠 AI-Powered Semantic Search\n- **Vector-based similarity search** over your entire research library (requires `[semantic]` extra)\n- **Multiple embedding models**: Default (free, local), OpenAI, and Gemini\n- **Intelligent results** with similarity scores and contextual matching\n- **Auto-updating database** with configurable sync schedules\n\n### 🔍 Search Your Library\n- Find papers, articles, and books by title, author, or content\n- Perform complex searches with multiple criteria\n- Browse collections, tags, and recent additions\n- Semantic search for conceptual and topic-based discovery\n\n### 📚 Access Your Content\n- Retrieve detailed metadata for any item (markdown or BibTeX export)\n- Get full text content (when available)\n- Look up items by BetterBibTeX citation key\n\n### 📝 Work with Annotations\n- Extract and search PDF annotations with page numbers\n- Access Zotero's native annotations\n- Create and update notes and annotations\n- Extract PDF table of contents \u002F outlines (requires `[pdf]` extra)\n\n### ✏️ Write Operations\n- **Add papers by DOI** with auto-fetched metadata and open-access PDF cascade (Unpaywall, arXiv, Semantic Scholar, PMC)\n- **Add papers by URL** (arXiv, DOI links, generic webpages) or from local files\n- Create and manage collections, update item metadata, batch-update tags\n- Find and merge duplicate items with dry-run preview\n- **Hybrid mode**: local reads + web API writes for local-mode users\n\n### 📊 Scite Citation Intelligence (optional `[scite]` extra)\n- **Citation tallies**: See how many papers support, contrast, or mention each item — the MCP version of the [Scite Zotero Plugin](https:\u002F\u002Fgithub.com\u002Fscitedotai\u002Fscite-zotero-plugin)\n- **Retraction alerts**: Scan your library for retracted or corrected papers\n- No Scite account required — uses public API endpoints\n\n### 🌐 Flexible Access Methods\n- Local mode for offline access (no API key needed)\n- Web API for cloud library access\n- Hybrid mode: read from local Zotero, write via web API\n\n## 🚀 Quick Install\n\n> **New to the command line?** Try the community-built [Zotero MCP Setup](https:\u002F\u002Fgithub.com\u002Fehawkin\u002Fzotero-mcp-setup) — includes a macOS GUI installer (DMG), one-click install scripts for Mac\u002FWindows, and a step-by-step guide. No Terminal experience needed.\n\n### Default Installation (core tools only)\n\nThe base install is lightweight — it includes search, metadata retrieval, annotations, and write operations. No ML\u002FAI dependencies are pulled in.\n\n#### Installing via uv (recommended)\n\n```bash\nuv tool install zotero-mcp-server\nzotero-mcp setup  # Auto-configure (Claude Desktop supported)\n```\n\n#### Installing via pip\n\n```bash\npip install zotero-mcp-server\nzotero-mcp setup  # Auto-configure (Claude Desktop supported)\n```\n\n#### Installing via pipx\n\n```bash\npipx install zotero-mcp-server\nzotero-mcp setup  # Auto-configure (Claude Desktop supported)\n```\n\n### Optional Extras\n\nHeavy ML\u002FPDF dependencies are separated into optional extras so the base install stays fast and small:\n\n| Extra | What it adds | Install command |\n|-------|-------------|-----------------|\n| `semantic` | Semantic search via ChromaDB, sentence-transformers, OpenAI\u002FGemini embeddings | `pip install \"zotero-mcp-server[semantic]\"` |\n| `pdf` | PDF outline extraction (PyMuPDF) and EPUB annotation support | `pip install \"zotero-mcp-server[pdf]\"` |\n| `scite` | [Scite](https:\u002F\u002Fscite.ai) citation intelligence — tallies and retraction alerts (no account needed) | `pip install \"zotero-mcp-server[scite]\"` |\n| `all` | Everything above | `pip install \"zotero-mcp-server[all]\"` |\n\nFor example, with uv:\n```bash\nuv tool install \"zotero-mcp-server[all]\"    # Full install with all features\nuv tool install \"zotero-mcp-server[semantic]\" # Just semantic search\n```\n\nIf you only need basic library access (search, read, annotate, write), the default install with no extras is all you need.\n\n#### Updating Your Installation\n\nKeep zotero-mcp up to date with the smart update command:\n\n```bash\n# Check for updates\nzotero-mcp update --check-only\n\n# Update to latest version (preserves all configurations)\nzotero-mcp update\n```\n\n## 🧠 Semantic Search\n\nZotero MCP now includes powerful AI-powered semantic search capabilities that let you find research based on concepts and meaning, not just keywords.\n\n### Setup Semantic Search\n\nDuring setup or separately, configure semantic search:\n\n```bash\n# Configure during initial setup (recommended)\nzotero-mcp setup\n\n# Or configure semantic search separately\nzotero-mcp setup --semantic-config-only\n```\n\n**Available Embedding Models:**\n- **Default (all-MiniLM-L6-v2)**: Free, runs locally, good for most use cases\n- **OpenAI**: Better quality, requires API key (`text-embedding-3-small` or `text-embedding-3-large`)\n- **Gemini**: Better quality, requires API key (`gemini-embedding-001`)\n\n**Update Frequency Options:**\n- **Manual**: Update only when you run `zotero-mcp update-db`\n- **Auto on startup**: Update database every time the server starts\n- **Daily**: Update once per day automatically\n- **Every N days**: Set custom interval\n\n### Using Semantic Search\n\nAfter setup, initialize your search database:\n\n```bash\n# Build the semantic search database (fast, metadata-only)\nzotero-mcp update-db\n\n# Build with full-text extraction (slower, more comprehensive)\nzotero-mcp update-db --fulltext\n\n# Use your custom zotero.sqlite path\nzotero-mcp update-db --fulltext --db-path \"\u002FYour_custom_path\u002Fzotero.sqlite\"\n\n# If you have embedding conflicts or changed models, force a rebuild\nzotero-mcp update-db --force-rebuild\n\n# Check database status\nzotero-mcp db-status\n```\n\n**Example Semantic Queries in your AI assistant:**\n- *\"Find research similar to machine learning concepts in neuroscience\"*\n- *\"Papers that discuss climate change impacts on agriculture\"*\n- *\"Research related to quantum computing applications\"*\n- *\"Studies about social media influence on mental health\"*\n- *\"Find papers conceptually similar to this abstract: [paste abstract]\"*\n\nThe semantic search provides similarity scores and finds papers based on conceptual understanding, not just keyword matching.\n\n## 🖥️ Setup & Usage\n\nFull documentation is available at [Zotero MCP docs](https:\u002F\u002Fstevenyuyy.com\u002Fzotero-mcp\u002F).\n\n**Requirements**\n- Python 3.10+\n- Zotero 7+ (for local API with full-text access)\n- An MCP-compatible client (e.g., Claude Desktop, ChatGPT Developer Mode, Cherry Studio, Chorus)\n\n**For ChatGPT setup: see the [Getting Started guide](.\u002Fdocs\u002Fgetting-started.md).**\n\n### For Claude Desktop (example MCP client)\n\n#### Configuration\nAfter installation, either:\n\n1. **Auto-configure** (recommended):\n   ```bash\n   zotero-mcp setup\n   ```\n\n2. **Manual configuration**:\n   Add to your `claude_desktop_config.json`:\n   ```json\n   {\n     \"mcpServers\": {\n       \"zotero\": {\n         \"command\": \"zotero-mcp\",\n         \"env\": {\n           \"ZOTERO_LOCAL\": \"true\"\n         }\n       }\n     }\n   }\n   ```\n\n#### Usage\n\n1. Start Zotero desktop (make sure local API is enabled in preferences)\n2. Launch Claude Desktop\n3. Access the Zotero-MCP tool through Claude Desktop's tools interface\n\nExample prompts:\n- \"Search my library for papers on machine learning\"\n- \"Find recent articles I've added about climate change\"\n- \"Summarize the key findings from my paper on quantum computing\"\n- \"Extract all PDF annotations from my paper on neural networks\"\n- \"Search my notes and annotations for mentions of 'reinforcement learning'\"\n- \"Show me papers tagged '#Arm' excluding those with '#Crypt' in my library\"\n- \"Search for papers on operating system with tag '#Arm'\"\n- \"Export the BibTeX citation for papers on machine learning\"\n- **\"Find papers conceptually similar to deep learning in computer vision\"** *(semantic search)*\n- **\"Research that relates to the intersection of AI and healthcare\"** *(semantic search)*\n- **\"Papers that discuss topics similar to this abstract: [paste text]\"** *(semantic search)*\n\n### For Cherry Studio\n\n#### Configuration\nGo to Settings -> MCP Servers -> Edit MCP Configuration, and add the following:\n\n```json\n{\n  \"mcpServers\": {\n    \"zotero\": {\n      \"name\": \"zotero\",\n      \"type\": \"stdio\",\n      \"isActive\": true,\n      \"command\": \"zotero-mcp\",\n      \"args\": [],\n      \"env\": {\n        \"ZOTERO_LOCAL\": \"true\"\n      }\n    }\n  }\n}\n```\nThen click \"Save\".\n\nCherry Studio also provides a visual configuration method for general settings and tools selection.\n\n## 🔧 Advanced Configuration\n\n### Using Web API Instead of Local API\n\nFor accessing your Zotero library via the web API (useful for remote setups):\n\n```bash\nzotero-mcp setup --no-local --api-key YOUR_API_KEY --library-id YOUR_LIBRARY_ID\n```\n\n### Environment Variables\n\n**Zotero Connection:**\n- `ZOTERO_LOCAL=true`: Use the local Zotero API (default: false)\n- `ZOTERO_API_KEY`: Your Zotero API key (for web API)\n- `ZOTERO_LIBRARY_ID`: Your Zotero library ID (for web API)\n- `ZOTERO_LIBRARY_TYPE`: The type of library (user or group, default: user)\n\n**Semantic Search:**\n- `ZOTERO_EMBEDDING_MODEL`: Embedding model to use (default, openai, gemini)\n- `OPENAI_API_KEY`: Your OpenAI API key (for OpenAI embeddings)\n- `OPENAI_EMBEDDING_MODEL`: OpenAI model name (text-embedding-3-small, text-embedding-3-large)\n- `OPENAI_BASE_URL`: Custom OpenAI endpoint URL (optional, for use with compatible APIs)\n- `GEMINI_API_KEY`: Your Gemini API key (for Gemini embeddings)\n- `GEMINI_EMBEDDING_MODEL`: Gemini model name (gemini-embedding-001)\n- `GEMINI_BASE_URL`: Custom Gemini endpoint URL (optional, for use with compatible APIs)\n- `ZOTERO_DB_PATH`: Custom `zotero.sqlite` path (optional)\n\n### Command-Line Options\n\n```bash\n# Run the server directly\nzotero-mcp serve\n\n# Specify transport method\nzotero-mcp serve --transport stdio|streamable-http|sse\n\n# Setup and configuration\nzotero-mcp setup --help                    # Get help on setup options\nzotero-mcp setup --semantic-config-only    # Configure only semantic search\nzotero-mcp setup-info                      # Show installation path and config info for MCP clients\n\n# Updates and maintenance\nzotero-mcp update                          # Update to latest version\nzotero-mcp update --check-only             # Check for updates without installing\nzotero-mcp update --force                  # Force update even if up to date\n\n# Semantic search database management\nzotero-mcp update-db                       # Update semantic search database (fast, metadata-only)\nzotero-mcp update-db --fulltext             # Update with full-text extraction (comprehensive but slower)\nzotero-mcp update-db --force-rebuild       # Force complete database rebuild\nzotero-mcp update-db --fulltext --force-rebuild  # Rebuild with full-text extraction\nzotero-mcp update-db --fulltext --db-path \"your_path_to\u002Fzotero.sqlite\" # Customize your zotero database path\nzotero-mcp db-status                       # Show database status and info\n\n# General\nzotero-mcp version                         # Show current version\n```\n\n## 📑 PDF Annotation Extraction\n\nZotero MCP includes advanced PDF annotation extraction capabilities:\n\n- **Direct PDF Processing**: Extract annotations directly from PDF files, even if they're not yet indexed by Zotero\n- **Enhanced Search**: Search through PDF annotations and comments\n- **Image Annotation Support**: Extract image annotations from PDFs\n- **Seamless Integration**: Works alongside Zotero's native annotation system\n\nFor optimal annotation extraction, it is **highly recommended** to install the [Better BibTeX plugin](https:\u002F\u002Fretorque.re\u002Fzotero-better-bibtex\u002Finstallation\u002F) for Zotero. The annotation-related functions have been primarily tested with this plugin and provide enhanced functionality when it's available.\n\n\nThe first time you use PDF annotation features, the necessary tools will be automatically downloaded.\n\n## 📚 Available Tools\n\n### 🧠 Semantic Search Tools\n- `zotero_semantic_search`: AI-powered similarity search with embedding models\n- `zotero_update_search_database`: Manually update the semantic search database\n- `zotero_get_search_database_status`: Check database status and configuration\n\n### 🔍 Search Tools\n- `zotero_search_items`: Search your library by keywords\n- `zotero_advanced_search`: Perform complex searches with multiple criteria\n- `zotero_get_collections`: List collections\n- `zotero_get_collection_items`: Get items in a collection\n- `zotero_get_tags`: List all tags\n- `zotero_get_recent`: Get recently added items\n- `zotero_search_by_tag`: Search your library using custom tag filters\n\n### 📚 Content Tools\n- `zotero_get_item_metadata`: Get detailed metadata (supports BibTeX export via `format=\"bibtex\"`)\n- `zotero_get_item_fulltext`: Get full text content\n- `zotero_get_item_children`: Get attachments and notes\n\n### 📝 Annotation & Notes Tools\n- `zotero_get_annotations`: Get annotations (including direct PDF extraction)\n- `zotero_get_notes`: Retrieve notes from your Zotero library\n- `zotero_search_notes`: Search in notes and annotations (including PDF-extracted)\n- `zotero_create_note`: Create a new note for an item (beta feature)\n\n### 📊 Scite Citation Intelligence Tools\n- `scite_enrich_item`: Get Scite citation tallies and retraction alerts for a paper\n- `scite_enrich_search`: Search your Zotero library with Scite-enriched results (tallies + alerts inline)\n- `scite_check_retractions`: Scan items for retractions and editorial notices\n\n### 📦 Item & Collection Management Tools\n- `zotero_add_by_doi`: Add a paper by DOI with automatic metadata and open-access PDF attachment\n- `zotero_add_by_url`: Add a paper by URL (arXiv, DOI URLs, and general webpages)\n- `zotero_add_from_file`: Import a local PDF or EPUB file with automatic DOI extraction\n- `zotero_create_collection`: Create a new collection (folder\u002Fproject) in your library\n- `zotero_search_collections`: Search for collections by name to find their keys\n- `zotero_manage_collections`: Add or remove items from collections\n- `zotero_update_item`: Update metadata for an existing item (title, tags, abstract, date, etc.)\n- `zotero_find_duplicates`: Find duplicate items by title and\u002For DOI\n- `zotero_merge_duplicates`: Merge duplicate items with dry-run preview; consolidates all child items\n- `zotero_get_pdf_outline`: Extract the table of contents \u002F outline from a PDF attachment\n- `zotero_search_by_citation_key`: Look up items by BetterBibTeX citation key (with Extra field fallback)\n\n## 🧪 Testing\n\n### Unit Tests\n```bash\nuv run pytest tests\u002F     # 294 tests, ~2 seconds\n```\n\n### Integration Test Plan\nA 45-point live integration test plan is included at `docs\u002Fintegration-test-plan.md`. It's designed to be given to Claude in Claude Desktop, which will execute each test against your real Zotero library. Tests cover all tools, PDF attachment cascade, attach_mode, BetterBibTeX lookups, and multi-step showcase prompts. See the file for full instructions.\n\n## 🔍 Troubleshooting\n\n### General Issues\n- **No results found**: Ensure Zotero is running and the local API is enabled. You need to toggle on `Allow other applications on this computer to communicate with Zotero` in Zotero preferences.\n- **Can't connect to library**: Check your API key and library ID if using web API\n- **Full text not available**: Make sure you're using Zotero 7+ for local full-text access\n- **Local library limitations**: Some functionality (tagging, library modifications) may not work with local JS API. Consider using web library setup for full functionality. (See the [docs](docs\u002Fgetting-started.md#local-library-limitations) for more info.)\n- **Installation\u002Fsearch option switching issues**: Database problems from changing install methods or search options can often be resolved with `zotero-mcp update-db --force-rebuild`\n\n### Semantic Search Issues\n- **\"Missing required environment variables\" when running update-db**: Run `zotero-mcp setup` to configure your environment, or the CLI will automatically load settings from your MCP client config (e.g., Claude Desktop)\n- **ChromaDB \u002F stale embedding model errors**: If you changed embedding models and see 404 errors (e.g., `text-embedding-004 is not found`), run `zotero-mcp update-db --force-rebuild` to recreate the collection with your current model. If that doesn't work, delete `~\u002F.config\u002Fzotero-mcp\u002Fchroma_db\u002F` and rebuild.\n- **Database update takes long**: By default, `update-db` is fast (metadata-only). For comprehensive indexing with full-text, use `--fulltext` flag. Use `--limit` parameter for testing: `zotero-mcp update-db --limit 100`\n- **Semantic search returns no results**: Ensure the database is initialized with `zotero-mcp update-db` and check status with `zotero-mcp db-status`\n- **Limited search quality**: For better semantic search results, use `zotero-mcp update-db --fulltext` to index full-text content (requires local Zotero setup)\n- **OpenAI\u002FGemini API errors**: Verify your API keys are correctly set and have sufficient credits\u002Fquota\n\n### Update Issues\n- **Update command fails**: Check your internet connection and try `zotero-mcp update --force`\n- **Configuration lost after update**: The update process preserves configs automatically, but check `~\u002F.config\u002Fzotero-mcp\u002F` for backup files\n\n## ☕ Support\n\nIf you find Zotero MCP useful, consider buying me a coffee!\n\n\u003Ca href=\"https:\u002F\u002Fbuymeacoffee.com\u002Fstevenyuyy\">\n  \u003Cimg src=\"https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FBuy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black\" alt=\"Buy Me a Coffee\">\n\u003C\u002Fa>\n\n## 📄 License\n\nMIT\n","Zotero MCP 是一个将 Zotero 研究库与 Claude 和其他 AI 助手通过 Model Context Protocol 连接起来的工具，支持讨论论文、获取摘要、分析引用等。项目采用 Python 语言开发，具备语义搜索、智能结果匹配和自动更新数据库等功能，并支持多种嵌入模型以实现基于向量的相似性搜索。此外，它还提供了强大的搜索功能，能够根据标题、作者或内容查找文献，浏览收藏集、标签及最近添加的内容。Zotero MCP 适用于需要高效管理和利用研究资料的学术场景，无论是本地还是网络环境下的 Zotero 库都能得到良好支持。",2,"2026-06-11 03:41:30","high_star"]