{"id":42443012,"url":"https://github.com/u9401066/zotero-keeper","last_synced_at":"2026-04-20T06:14:53.804Z","repository":{"id":328273716,"uuid":"1114887227","full_name":"u9401066/zotero-keeper","owner":"u9401066","description":"AI-powered research toolkit integrating PubMed search, Zotero management, and VS Code extension with OpenURL institutional access","archived":false,"fork":false,"pushed_at":"2026-03-04T07:00:53.000Z","size":1065,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-04T13:08:06.929Z","etag":null,"topics":["ai-research","literature-search","mcp","pubmed","reference-manager","vscode-extension","zotero"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/u9401066.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":null,"custom":null}},"created_at":"2025-12-12T03:14:02.000Z","updated_at":"2026-03-04T07:00:39.000Z","dependencies_parsed_at":"2025-12-13T11:07:33.897Z","dependency_job_id":null,"html_url":"https://github.com/u9401066/zotero-keeper","commit_stats":null,"previous_names":["u9401066/zotero-keeper"],"tags_count":26,"template":false,"template_full_name":null,"purl":"pkg:github/u9401066/zotero-keeper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u9401066%2Fzotero-keeper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u9401066%2Fzotero-keeper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u9401066%2Fzotero-keeper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u9401066%2Fzotero-keeper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/u9401066","download_url":"https://codeload.github.com/u9401066/zotero-keeper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/u9401066%2Fzotero-keeper/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30281165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-09T02:23:26.802Z","status":"ssl_error","status_checked_at":"2026-03-09T02:22:46.175Z","response_time":61,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-research","literature-search","mcp","pubmed","reference-manager","vscode-extension","zotero"],"created_at":"2026-01-28T07:09:24.320Z","updated_at":"2026-04-20T06:14:53.781Z","avatar_url":"https://github.com/u9401066.png","language":"Python","funding_links":[],"categories":["Biomedical Research \u0026 Genomics"],"sub_categories":[],"readme":"# Zotero Keeper 📚\n\nLet AI manage your references! A MCP Server connecting VS Code Copilot / Claude Desktop to your local Zotero library.\n\n[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)\n[![MCP SDK](https://img.shields.io/badge/MCP-FastMCP-green.svg)](https://github.com/modelcontextprotocol/python-sdk)\n[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)\n[![Zotero 7/8](https://img.shields.io/badge/Zotero-7%20%2F%208-red.svg)](https://www.zotero.org/)\n[![CI](https://github.com/u9401066/zotero-keeper/actions/workflows/ci.yml/badge.svg)](https://github.com/u9401066/zotero-keeper/actions/workflows/ci.yml)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n\n\u003e 🌐 **English** | **[繁體中文](README.zh-TW.md)**\n\n---\n\n## 🚀 One-Click Install (VS Code)\n\n\u003e **Prerequisites**: [Zotero 7 or 8](https://www.zotero.org/download/) must be running\n\n\u003ca href=\"vscode:mcp/install?%7B%22name%22%3A%22zotero-keeper%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22zotero-keeper%22%5D%7D\"\u003e\u003cimg src=\"https://img.shields.io/badge/VS%20Code-Install%20MCP%20Server-007ACC?style=for-the-badge\u0026logo=visualstudiocode\" alt=\"Install in VS Code\"\u003e\u003c/a\u003e\n\u003ca href=\"vscode-insiders:mcp/install?%7B%22name%22%3A%22zotero-keeper%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22zotero-keeper%22%5D%7D\"\u003e\u003cimg src=\"https://img.shields.io/badge/VS%20Code%20Insiders-Install%20MCP%20Server-24bfa5?style=for-the-badge\u0026logo=visualstudiocode\" alt=\"Install in VS Code Insiders\"\u003e\u003c/a\u003e\n\n\u003e 💡 **Requires [uv](https://docs.astral.sh/uv/getting-started/installation/)** - Click installs automatically via `uvx zotero-keeper`\n\n---\n\n## ✨ What is this?\n\n**Zotero Keeper** is a [MCP Server](https://modelcontextprotocol.io/) that lets your AI assistant:\n\n- 🔍 **Search references**: \"Find papers about CRISPR from 2024\"\n- 📖 **View details**: \"What's the abstract of this article?\"\n- ➕ **Add references**: \"Add this DOI to my Zotero\" (with auto-fetch metadata!)\n- 🔄 **PubMed integration**: \"Search PubMed, skip what I already have\"\n- 📁 **Interactive save**: Shows collection options for you to choose!\n\nNo more manually searching, copying, pasting. Just tell your AI in natural language!\n\n---\n\n## ✨ Features\n\n- **🔌 MCP Native**: Built with FastMCP SDK for seamless AI integration\n- **📖 MCP Resources**: Browse Zotero data via URIs (`zotero://collections`, etc.)\n- **💬 MCP Elicitation**: Interactive collection selection with numbered options\n- **🔒 Auto-fetch Metadata**: DOI/PMID → complete abstract + all fields automatically!\n- **📊 Citation Metrics**: RCR and NIH Percentile stored in Zotero extra fields\n- **🛡️ Collection Validation**: Use `collection_name` for safer auto-validation\n- **📖 Read Operations**: Search, list, and retrieve items from local Zotero\n- **✏️ Write Operations**: Add references via Connector API\n- **🧠 Smart Features**: Duplicate detection, validation, intelligent import\n- **📁 Collection Support**: Nested collections (folders) with hierarchy\n- **🏗️ Clean Architecture**: DDD with onion architecture\n- **🔒 No Cloud Required**: All operations are local\n\n---\n\n## 🚀 Quick Start\n\n### Prerequisites\n\n- ✅ [Python 3.12+](https://www.python.org/downloads/)\n- ✅ [Zotero 7 or 8](https://www.zotero.org/download/) (must be running)\n- ✅ [VS Code](https://code.visualstudio.com/) + GitHub Copilot, or [Claude Desktop](https://claude.ai/)\n- ✅ [uv](https://docs.astral.sh/uv/getting-started/installation/) (recommended)\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/u9401066/zotero-keeper.git\ncd zotero-keeper/mcp-server\n\n# Install with uv (required)\nuv sync --extra all\n\n# Test (make sure Zotero is running)\nuv run python -m zotero_mcp\n```\n\n### Configure VS Code Copilot\n\nCreate `.vscode/mcp.json` in your workspace:\n\n```json\n{\n  \"servers\": {\n    \"zotero-keeper\": {\n      \"type\": \"stdio\",\n      \"command\": \"uv\",\n      \"args\": [\n        \"run\",\n        \"--directory\",\n        \"/path/to/zotero-keeper/mcp-server\",\n        \"python\", \"-m\", \"zotero_mcp\"\n      ]\n    }\n  }\n}\n```\n\n### Configure Claude Desktop\n\nAdd to `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"zotero-keeper\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"python\", \"-m\", \"zotero_mcp\"],\n      \"cwd\": \"/path/to/zotero-keeper/mcp-server\"\n    }\n  }\n}\n```\n\n\u003e 💡 Use absolute paths and ensure [uv](https://docs.astral.sh/uv/) is installed.\n\n### Common Environment Variables\n\nIf you run the server directly, these are the main settings you may want to provide via `.env` or your MCP launcher configuration:\n\n```bash\nZOTERO_HOST=localhost\nZOTERO_PORT=23119\nZOTERO_TIMEOUT=30\nNCBI_EMAIL=your.email@example.com\n# NCBI_API_KEY=your_api_key_here\n# ZOTERO_KEEPER_ENABLE_LEGACY_PUBMED_TOOLS=1\n# PUBMED_SEARCH_PATH=/path/to/pubmed-search-mcp\n```\n\n- Use `NCBI_EMAIL` and optional `NCBI_API_KEY` for higher NCBI/PubMed rate limits.\n- Use `ZOTERO_KEEPER_ENABLE_LEGACY_PUBMED_TOOLS=1` only if you intentionally want keeper's older PubMed bridge/import tools.\n- Use `PUBMED_SEARCH_PATH` only during local development when you want keeper to import a checked-out `pubmed-search-mcp` tree instead of the installed package.\n\n---\n\n## 📚 Documentation Map\n\n- [README.zh-TW.md](README.zh-TW.md) — Traditional Chinese overview\n- [mcp-server/README.md](mcp-server/README.md) — focused server usage and tool reference\n- [vscode-extension/README.md](vscode-extension/README.md) — VS Code extension setup and UX\n- [docs/COLLABORATION_WORKFLOW.md](docs/COLLABORATION_WORKFLOW.md) — collaboration-safe flow between pubmed-search-mcp and keeper\n- [docs/tools-reference.md](docs/tools-reference.md) — parameter reference and examples for public tools\n- [docs/faq.md](docs/faq.md) — installation, troubleshooting, and workflow FAQ\n- [docs/ZOTERO_LOCAL_API.md](docs/ZOTERO_LOCAL_API.md) — Zotero API capability notes and limitations\n- [ARCHITECTURE.md](ARCHITECTURE.md) — component and layering overview\n- [CONTRIBUTING.md](CONTRIBUTING.md) — development workflow and contribution guide\n\n---\n\n## 🔧 Available Tools (23 default public + 5 legacy opt-in)\n\n\u003e 💡 **Tip**: Most read operations can also be done via [MCP Resources](#-mcp-resources-browsable-data) without calling tools.\n\n### 📖 Core Tools (server.py - 6 tools)\n\n| Tool | Description | Example |\n|------|-------------|---------|\n| `check_connection` | Test Zotero connectivity | \"Is Zotero running?\" |\n| `search_items` | Search references | \"Find papers about CRISPR\" |\n| `get_item` | Get item details | \"Show abstract for key:ABC123\" |\n| `list_items` | List recent items | \"Show papers in collection X\" |\n| `list_tags` | List all tags | \"What tags have I used?\" |\n| `get_item_types` | Available item types | \"What types can I add?\" |\n\n### 📁 Collection Tools (server.py - 5 tools)\n\n\u003e ⚠️ These can also be accessed via `zotero://collections/...` Resources\n\n| Tool | Description | Equivalent Resource |\n|------|-------------|--------------------|\n| `list_collections` | List all folders | `zotero://collections` |\n| `get_collection` | Get collection details | `zotero://collections/{key}` |\n| `get_collection_items` | Items in a collection | `zotero://collections/{key}/items` |\n| `get_collection_tree` | Hierarchical tree view | `zotero://collections/tree` |\n| `find_collection` | Find by name | — (Tool only) |\n\n### ✏️ Save Tools (interactive_tools.py - 2 tools)\n\n\u003e 📊 **Auto RCR**: When PMID is provided, automatically fetches Relative Citation Ratio from iCite and stores in Zotero's extra field\n\n| Tool | Description | Example |\n|------|-------------|--------|\n| `interactive_save` ⭐ | Interactive save + auto RCR | \"Save this paper to Zotero\" |\n| `quick_save` | Quick save + auto RCR | \"Quick save to AI Research\" |\n\n### 🔍 Saved Search Tools (saved_search_tools.py - 3 tools)\n\n| Tool | Description | Example |\n|------|-------------|---------|\n| `list_saved_searches` | List all saved searches | \"What saved searches exist?\" |\n| `run_saved_search` | Execute a saved search | \"Which papers have no PDF?\" |\n| `get_saved_search_details` | Get search conditions | \"What's in 'Missing PDF' search?\" |\n\n### 🔍 Advanced Search \u0026 Ownership Check (search_tools.py - 2 public tools)\n\n| Tool | Description | Example |\n|------|-------------|---------|\n| `advanced_search` ⭐ | Multi-condition search (itemType, tag, qmode) | \"Find all journal articles tagged with AI\" |\n| `check_articles_owned` | Check if PMIDs exist in Zotero | \"Do I have these PMIDs?\" |\n\n### 📥 Import Tools (single public handoff)\n\n\u003e 🤝 **Collaboration-safe default**: PubMed search/discovery/export lives in pubmed-search-mcp. Zotero Keeper exposes one public import handoff: `import_articles`.\n\n| Tool | Description | Example |\n|------|-------------|--------|\n| `import_articles` ⭐ | Single public import entry for JSON articles or RIS text | \"Import these PubMed results to AI Research\" |\n\n#### Legacy PubMed bridge tools\n\n`search_pubmed_exclude_owned`, `quick_import_pmids`, `import_ris_to_zotero`, `import_from_pmids`, and `batch_import_from_pubmed` are now hidden by default to avoid duplicating pubmed-search-mcp.\n\nIf you intentionally want the old standalone keeper behavior, set `ZOTERO_KEEPER_ENABLE_LEGACY_PUBMED_TOOLS=1` before starting the server.\n\n### 📊 Analytics Tools (analytics_tools.py - 2 tools)\n\n| Tool | Description | Example |\n|------|-------------|--------|\n| `get_library_stats` | Library statistics (year/author/journal) | \"Show my library statistics\" |\n| `find_orphan_items` | Find unorganized items | \"Which papers need organizing?\" |\n\n### 📎 Attachment \u0026 Fulltext Tools (attachment_tools.py - 2 tools)\n\n\u003e 🗂️ **PDF Access**: List attached PDFs and read Zotero-indexed fulltext. Requires `ZOTERO_DATA_DIR` for file paths.\n\n| Tool | Description | Example |\n|------|-------------|--------|\n| `get_item_attachments` | List PDFs/snapshots for an item | \"What attachments does key:X42A7DEE have?\" |\n| `get_item_fulltext` | Get Zotero-indexed fulltext content | \"Read the full text of key:X42A7DEE\" |\n\n#### Recommended PubMed → Zotero workflow\n\n```python\n# 1. Search with pubmed-search-mcp\nresults = unified_search(\"anesthesia AI\", output_format=\"json\")\n\n# 2. Optional: filter against local Zotero\nowned = check_articles_owned([article[\"pmid\"] for article in results[\"articles\"] if article.get(\"pmid\")])\n\n# 3. Import selected records into Zotero\nimport_articles(\n  articles=results[\"articles\"],\n  collection_name=\"AI Research\"\n)\n```\n\n### 🤝 Collaboration-Safe Setup (Summary)\n\n- pubmed-search-mcp runs search/discovery/export; zotero-keeper handles duplicate checks and the single `import_articles` handoff.\n- Ensure pubmed-search-mcp is installed or the submodule is present; set `PUBMED_SEARCH_PATH` if you rely on a local checkout.\n- Keep legacy PubMed bridge tools disabled unless you set `ZOTERO_KEEPER_ENABLE_LEGACY_PUBMED_TOOLS=1` intentionally.\n- Full checklist: see `docs/COLLABORATION_WORKFLOW.md`.\n\n#### advanced_search Examples\n\n```python\n# 🔍 依文獻類型搜尋\nadvanced_search(item_type=\"journalArticle\")  # 只找期刊論文\nadvanced_search(item_type=\"book\")  # 只找書籍\nadvanced_search(item_type=\"-attachment\")  # 排除附件\n\n# 🏷️ 依標籤搜尋\nadvanced_search(tag=\"AI\")  # 具有 AI 標籤的文獻\nadvanced_search(tags=[\"AI\", \"Review\"])  # 同時具有兩個標籤 (AND)\nadvanced_search(tag=\"AI || ML\")  # 具有任一標籤 (OR)\n\n# 📝 全文搜尋 (含 abstract)\nadvanced_search(q=\"XGBoost\", qmode=\"everything\")  # 搜尋摘要內容\n\n# 🌟 組合條件\nadvanced_search(\n    q=\"machine learning\",\n    item_type=\"journalArticle\",\n    tag=\"AI\",\n    sort=\"dateAdded\",\n    direction=\"desc\"\n)\n```\n\n---\n\n## 📖 MCP Resources (Browsable Data)\n\nNo tool calls needed! AI can directly browse Zotero data:\n\n| Resource URI | Description |\n|--------------|-------------|\n| `zotero://collections` | All collections |\n| `zotero://collections/tree` | Collection hierarchy |\n| `zotero://collections/{key}` | Specific collection |\n| `zotero://collections/{key}/items` | Items in collection |\n| `zotero://items` | Recent items |\n| `zotero://items/{key}` | Item details |\n| `zotero://tags` | All tags |\n| `zotero://searches` | Saved searches |\n| `zotero://searches/{key}` | Search details |\n| `zotero://schema/item-types` | Available item types |\n\n---\n\n## 🎯 Interactive Save (Recommended!)\n\nThe `interactive_save` tool uses **MCP Elicitation** to show collection options:\n\n```\nUser: \"Save this DOI:10.1234/example paper to Zotero\"\n\n[MCP Elicitation pops up]\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n📚 Saving: Deep Learning for Medical Imaging\n\n⭐ Suggested:\n   1. AI Research (match: 90%) - Title matches\n   2. Medical Imaging (match: 75%) - Keyword matches\n\n📂 All Collections:\n   3. Biology (12 items)\n   4. Chemistry (8 items)\n   5. To Read (23 items)\n\n0. Save to My Library (no collection)\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n\nEnter the number of your choice: [User enters: 1]\n\nAI: ✅ Saved to 'AI Research' collection!\n```\n\n### 🔒 Data Integrity: Auto-fetch Metadata\n\nWhen you provide a **DOI** or **PMID**, the tool automatically fetches complete metadata:\n\n- **DOI** → CrossRef API → Full abstract, authors, journal, date\n- **PMID** → PubMed API → Full abstract, MeSH terms, affiliations\n\nNo more missing abstracts! Just provide the identifier.\n\n---\n\n## 📁 Collection Organization\n\nZotero supports **nested collections**. Recommended strategies:\n\n### By Topic (Recommended)\n```\n📁 My Library\n├── 📁 Research Topics\n│   ├── 📂 CRISPR Gene Editing\n│   ├── 📂 Machine Learning in Medicine\n│   └── 📂 Anesthesia Safety\n├── 📁 Projects\n│   ├── 📂 2024 Paper Draft\n│   └── 📂 PhD Thesis\n└── 📁 Reading List\n    ├── 📂 To Read\n    └── 📂 Important\n```\n\n\u003e 💡 **Best Practice**: Use **collections** for primary organization, **tags** for cross-cutting attributes (e.g., \"to-read\", \"important\", \"review\").\n\n---\n\n## 🔬 PubMed Integration\n\nWorks seamlessly with [pubmed-search-mcp](https://github.com/u9401066/pubmed-search-mcp):\n\n```\nYou: \"Find new anesthesia AI papers from 2024 that I don't have\"\n\nAI executes:\n1. pubmed-search-mcp: unified_search(\"anesthesia AI\", min_year=2024, output_format=\"json\")\n  → Found 30 candidate articles\n\n2. zotero-keeper: check_articles_owned([...pmids...])\n  → Detects which PMIDs already exist locally\n\n3. zotero-keeper: import_articles(articles=selected_articles, collection_name=\"AI Research\")\n  → Imports the selected records into Zotero\n\nYou: Done! 25 new papers in Zotero\n```\n\n### Install PubMed Integration\n\n```bash\ncd mcp-server\nuv sync --extra pubmed\n```\n\n---\n\n## 🌐 Remote Zotero Setup\n\nIf Zotero runs on another computer:\n\n### 1. On Zotero Machine (Windows)\n\n```powershell\n# Enable Local API (in Zotero → Tools → Developer → Run JavaScript)\nZotero.Prefs.set(\"httpServer.localAPI.enabled\", true)\n\n# Open firewall\nnetsh advfirewall firewall add rule name=\"Zotero\" dir=in action=allow protocol=TCP localport=23119\n\n# Setup port proxy (Zotero only listens on 127.0.0.1)\nnetsh interface portproxy add v4tov4 listenaddress=0.0.0.0 listenport=23119 connectaddress=127.0.0.1 connectport=23119\n```\n\n### 2. Configure MCP Server\n\n```json\n{\n  \"env\": {\n    \"ZOTERO_HOST\": \"192.168.1.100\",\n    \"ZOTERO_PORT\": \"23119\"\n  }\n}\n```\n\n---\n\n## 🏗️ Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│           AI Agent (VS Code / Claude)           │\n└──────────────────────┬──────────────────────────┘\n                       │ MCP Protocol\n                       │ ├── Tools (22)\n                       │ ├── Resources (10 URIs)\n                       │ └── Elicitation (interactive input)\n                       ▼\n┌─────────────────────────────────────────────────┐\n│              Zotero Keeper MCP Server           │\n│  ┌───────────────────────────────────────────┐  │\n│  │  MCP Layer                                │  │\n│  │  ├── server.py (11 tools: 6 core + 5 collection) │\n│  │  ├── resources.py (10 URIs, incl. collections)   │\n│  ├── interactive_tools.py (2 save tools)  │  │\n│  │  ├── saved_search_tools.py (3 tools)      │  │\n│  │  ├── search_tools.py (3 tools)            │  │\n│  │  ├── pubmed_tools.py (2 tools)            │  │\n│  │  ├── batch_tools.py (1 tool)              │  │\n│  │  └── smart_tools.py (helpers only)        │  │\n│  └───────────────────────────────────────────┘  │\n└──────────────────────┬──────────────────────────┘\n                       │ HTTP (port 23119)\n                       ▼\n┌─────────────────────────────────────────────────┐\n│              Zotero Desktop Client              │\n│  ├── Local API (/api/...) → Read               │\n│  └── Connector API (/connector/...) → Write    │\n└─────────────────────────────────────────────────┘\n```\n\n---\n\n## ⚠️ Zotero API Limitations (Important!)\n\n### API Capability Matrix\n\nZotero provides **two local APIs**, but neither supports full CRUD:\n\n| API | Endpoint | Read | Create | Update | Delete |\n|-----|----------|:----:|:------:|:------:|:------:|\n| **Local API** | `/api/...` | ✅ | ❌ | ❌ | ❌ |\n| **Connector API** | `/connector/...` | ❌ | ✅ | ❌ | ❌ |\n\n### 🔍 Technical Details\n\n**Local API** (port 23119):\n- Designed for reading Zotero data (items, collections, tags)\n- Per [official source code](https://github.com/zotero/zotero/blob/main/chrome/content/zotcom/server/server_localAPI.js#L28-L43): **\"Write access is not yet supported.\"**\n- DELETE/PATCH/PUT methods return `501 Not Implemented`\n\n**Connector API** (port 23119):\n- Designed for browser extensions to **save new items**\n- `saveItems` endpoint: **Always creates NEW items, never updates**\n- Even if you import the same PMID twice → creates duplicate items\n- No `updateItem` or `deleteItem` endpoints exist\n\n### 🔴 Operations NOT Supported\n\n| Operation | API Support | Technical Reason |\n|-----------|-------------|------------------|\n| ❌ **Delete items** | 501 Not Implemented | Local API is read-only |\n| ❌ **Update items** | 501 Not Implemented | Local API is read-only |\n| ❌ **Move items to collection** | Cannot modify | Connector API only creates, never updates |\n| ❌ **Add tags to existing items** | Cannot modify | No update endpoint available |\n| ❌ **Create collections** | 400 Bad Request | Connector API doesn't support it |\n| ❌ **Delete collections** | 501 Not Implemented | Local API is read-only |\n| ❌ **Merge duplicates** | No API | Must use Zotero GUI |\n\n### 💡 What This Means\n\n**\"Smart Management\" Limitations:**\n\n```\n❌ Cannot do:\n- \"Move these 10 papers to another collection\"\n- \"Delete all duplicate references\"\n- \"Help me organize my collections\"\n- \"Archive old papers\"\n\n✅ Can do:\n- \"Add to specific collection when importing\" (at creation time)\n- \"Search for matching references\" (then handle manually)\n- \"List potential duplicates\" (but manual deletion needed)\n```\n\n### 🛠️ Workarounds\n\n| Need | Alternative |\n|------|-------------|\n| Organize collections | Drag \u0026 drop in Zotero GUI |\n| Delete duplicates | Zotero → Tools → \"Merge duplicates\" |\n| Batch operations | Use [Zotero Actions \u0026 Tags](https://github.com/windingwind/zotero-actions-tags) plugin |\n| Auto-categorize | Use [Zutilo](https://github.com/wshanks/Zutilo) plugin |\n\n### 🔮 Future Possibilities\n\nZotero team is working on **Local API write support**:\n- [GitHub Issue #1320](https://github.com/zotero/zotero/issues/1320) - Request for write support\n- Expected in future Zotero releases (8.x+)\n\n**We'll update zotero-keeper as soon as Zotero supports it!**\n\n---\n\n### 🌟 Local API Exclusive: Execute Saved Searches\n\n| API | Execute Saved Search |\n|-----|---------------------|\n| Web API (api.zotero.org) | ❌ Can only read search metadata |\n| **Local API** | ✅ Can execute and retrieve results! |\n\n**Recommended Saved Searches** (create once, use forever):\n\n| Name | Condition | AI Prompt |\n|------|-----------|-----------|\n| Missing PDF | Attachment File Type is not PDF | \"Which papers have no PDF?\" |\n| Missing DOI | DOI is empty | \"Which items lack DOI?\" |\n| Recent | Date Added in last 7 days | \"What did I add this week?\" |\n| Unread | Tag is not \"read\" | \"What haven't I read?\" |\n| Duplicates | Similar titles | \"Potential duplicate items?\" |\n\n---\n\n## 📦 Installation \u0026 Distribution Paths\n\nWe support both developer-oriented and researcher-friendly entry points today, while keeping room for simpler packaging later.\n\n| Path | Status | Best for |\n|------|--------|----------|\n| VS Code extension | ✅ Available now | Researchers who want guided setup inside VS Code |\n| Source checkout + `uv sync` | ✅ Available now | Contributors and local development |\n| Direct MCP registration via `uvx zotero-keeper` | ✅ Available now | Existing MCP-capable clients |\n| Standalone executable | 🚧 Planned | Users who do not want to install Python/uv |\n| Homebrew / Chocolatey | 🚧 Planned | OS-level package manager workflows |\n\n\u003e 💡 Want to help improve installation? See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## 🤔 Troubleshooting\n\n### Can't connect to Zotero?\n\n1. Make sure Zotero is running\n2. Test: `curl http://127.0.0.1:23119/connector/ping`\n3. Should return: `Zotero is running`\n\n### MCP Server not found?\n\n1. Use absolute paths\n2. Check Python environment\n3. Restart VS Code / Claude Desktop\n\n### PubMed features missing?\n\n```bash\ncd mcp-server\nuv sync --extra pubmed\n```\n\n---\n\n## 📚 Resources\n\n- [CHANGELOG](CHANGELOG.md) - Release notes\n- [ARCHITECTURE](ARCHITECTURE.md) - Technical architecture\n- [CONTRIBUTING](CONTRIBUTING.md) - How to contribute\n- [ROADMAP](ROADMAP.md) - Development roadmap\n- [docs/tools-reference.md](docs/tools-reference.md) - Full MCP tools parameter reference\n- [docs/faq.md](docs/faq.md) - Frequently asked questions\n- [pubmed-search-mcp](https://github.com/u9401066/pubmed-search-mcp) - PubMed search (Apache 2.0)\n\n---\n\n## 🤝 Contributing\n\nContributions welcome! See [CONTRIBUTING.md](CONTRIBUTING.md).\n\n- 🐛 [Report Bugs](https://github.com/u9401066/zotero-keeper/issues)\n- 💡 [Request Features](https://github.com/u9401066/zotero-keeper/issues)\n- 🔧 [Submit PRs](https://github.com/u9401066/zotero-keeper/pulls)\n\n---\n\n## 📄 License\n\nApache 2.0 - See [LICENSE](LICENSE)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Made with ❤️ for researchers\u003cbr\u003e\n  Let AI manage your references, focus on your research!\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu9401066%2Fzotero-keeper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fu9401066%2Fzotero-keeper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fu9401066%2Fzotero-keeper/lists"}