| name | zotero-mcp |
| description | Interface with Zotero's MCP server to search and retrieve bibliographic data using advanced semantic search and multi-strategy approaches. Designed for output as a plain markdown formatted outline, suitable for pasting into Logseq. Also offers side-by-side translation of Chinese titles and abstracts for improved English language search within Logseq. Context-aware - uses agents in Claude Code, batched searches in Claude Desktop. |
Zotero MCP Search Skill
Interface with Zotero's MCP server to search and retrieve bibliographic data using advanced semantic search and multi-strategy approaches.
Designed for plain markdown outline output: This skill generates bibliographies formatted as plain markdown outlines suitable for pasting into Logseq with:
- Outline hierarchy (nested bullets, no markdown headers)
- Compact citation format (Author, Year. Title)
- Side-by-side Chinese-English translations for improved English language search
- Plain text (no bold styling)
- Zotero item links
Context-Aware Skill: This skill automatically adapts its strategy based on the environment:
- Claude Code: Uses autonomous agents for comprehensive multi-step searches
- Claude Desktop: Uses batched manual searches with safety limits
Core Philosophy
Search comprehensively, not narrowly. Never settle for a single search attempt. Always:
- Use semantic search for conceptual discovery
- Try multiple search angles and variations
- Combine different search methods
- Iteratively refine based on results
- Ask clarifying questions when needed
- Format bibliographies for Logseq with proper outline structure
Environment Detection
Detect which environment you're running in:
- Claude Code: Agents available (Task tool), no conversation crash risk
- Claude Desktop: No agents, conversation deletion risk with large responses
How to tell: Check if Task tool is available in your tool list.
PART 1: Claude Desktop Strategy
⚠️ CRITICAL: Avoiding Claude Desktop Crashes ⚠️
KNOWN BUG: Claude Desktop has a critical bug where large MCP responses cause request timeouts that DELETE the entire conversation without warning or recovery.
Safe Search Strategy: Batched Iteration
To get comprehensive results safely, use iterative batched searches:
✅ SAFE: Multiple small searches
- Each search limited to 10-15 results maximum
- Multiple searches with different angles/filters
- Combine results across searches
❌ UNSAFE: Single large search
- limit=50 or higher in one call
- Risks conversation deletion
- No recovery possible
Recommended Approaches for Claude Desktop
Approach 1: Multi-Angle Coverage (Preferred)
Instead of one search with limit=50, do 5 searches with different angles:
1. Semantic search: "main concept" (limit=10)
2. Semantic search: "related concept variation" (limit=10)
3. Keyword search: "specific terms" (limit=10)
4. Tag-based search: relevant tags (limit=10)
5. Notes/annotations search: "concept" (limit=10)
This gives ~50 results from different perspectives, safer than one large call.
Approach 2: Iterative Interactive
For user-guided exploration:
1. First batch: limit=10
2. Present results
3. Ask: "Would you like more results, or shall I search from a different angle?"
4. Next batch based on user feedback
Default Limits for Claude Desktop
Always use these safe defaults:
limit=10 for initial searcheslimit=15 if user explicitly needs more- Never exceed limit=20 in a single call
- For comprehensive results: use multiple searches, not larger limits
PART 2: Claude Code Strategy
Agent-First Approach
When running in Claude Code, use autonomous agents for comprehensive searches.
When to Use Agents (Claude Code Only)
Use agents when:
- User needs comprehensive literature searches
- User asks exploratory questions ("What do I have about...")
- User needs multi-angle search coverage
- User wants thorough, curated results
- User's query is conceptual or thematic
Don't use agents when:
- User asks for a single specific paper by exact title
- User just wants to see recent additions
- User is browsing collections interactively
Agent Task Patterns
Pattern 1: Comprehensive Topic Search
User request: "Find me papers about [topic]"
Agent task:
Search my Zotero library comprehensively for papers about [topic].
Use multiple search strategies autonomously:
1. SEMANTIC SEARCHES (5-6 variations)
- Try natural language phrasings
- Try different conceptual angles
- Use synonyms and related terms
- No limit restrictions - get comprehensive results
2. KEYWORD SEARCHES (3-4 variations)
- Try exact terms and variations
- Try broader/narrower terms
- Try related methodology terms
3. TAG-BASED SEARCHES
- First use zotero_get_tags to discover relevant tags
- Then search by multiple relevant tags
- Try tag combinations
4. FULL-TEXT & ANNOTATIONS
- Use zotero_search_notes for the concept
- Use zotero_get_annotations to find highlights
- Search for related concepts in notes
5. SYNTHESIS
- Combine all results and deduplicate
- Identify the 20-30 most relevant papers
- Group by theme/approach if applicable
- Provide brief relevance explanations
Return a curated list with:
- Paper metadata (title, authors, year)
- Why each paper is relevant
- Thematic groupings if applicable
- Coverage note (which strategies found what)
Pattern 2: Author-Focused Search
User request: "What do I have by/about [author]?"
Agent task:
Find all items related to [author] in my Zotero library.
Search comprehensively:
1. DIRECT AUTHORSHIP
- zotero_search_items with author="[author]"
- zotero_advanced_search with author field
2. CITATIONS & MENTIONS
- zotero_search_notes: "[author]" (cited in my notes)
- zotero_get_annotations: "[author]" (mentioned in highlights)
- zotero_semantic_search: "[author]'s main concepts/theories"
3. RELATED WORK
- Search for concepts/theories associated with this author
- Search for methodologies they use
- Search for co-authors
4. SYNTHESIS
- Organize by: (1) authored by, (2) cited in my notes, (3) related concepts
- Include temporal overview if relevant
- Note any thematic clusters
Return organized results with context about how each item relates to [author].
Pattern 3: Concept in Context
User request: "Research about X in context Y"
Agent task:
Find papers about [X] in the context of [Y].
Multi-angle search strategy:
1. COMBINED SEARCHES
- Semantic: "X in Y" + variations
- Semantic: "Y approaches to X"
- Advanced: keyword=X AND keyword=Y
- Advanced: keyword=X AND keyword=[Y synonyms]
2. SEPARATE THEN CROSS-REFERENCE
- Find strong X papers
- Find strong Y papers
- Identify overlap and connections
- Check if X papers mention Y in fulltext
- Check if Y papers mention X in fulltext
3. TAG ANALYSIS
- Get tags related to X
- Get tags related to Y
- Search items tagged with both domains
- Find bridging concepts in tags
4. ANNOTATION MINING
- Search notes for X+Y together
- Search notes for X and Y separately
- Check if you've annotated connections
5. SYNTHESIS
- Papers directly about X in Y context
- Papers about X that discuss Y
- Papers about Y that discuss X
- Papers that bridge both (even if not explicit)
Return results grouped by relevance strength and connection type.
Pattern 4: Exploratory Discovery
User request: "What's related to X?" or "Explore my library for X"
Agent task:
Explore my Zotero library to discover all material related to [X].
Comprehensive discovery approach:
1. DIRECT SEARCHES (Cast wide net)
- Semantic search: multiple phrasings of X
- Keyword search: X and synonyms
- Tag search: X-related tags
- Notes/annotations: X mentions
2. EXPANSION PHASE
- Analyze top results to identify:
* Related concepts and theories
* Related methodologies
* Related application domains
* Related authors
- Search for each of these expansions
3. DEEP EXPLORATION
- For promising papers, check fulltext for related concepts
- Look at tags on promising papers, search those tags
- Check annotations for related ideas
- Look for cited works mentioned in your notes
4. THEMATIC CLUSTERING
- Group all findings by themes/approaches
- Identify conceptual clusters
- Note connections between clusters
- Highlight surprising/unexpected connections
5. SYNTHESIS
- Core papers directly about X
- Related theoretical frameworks
- Methodological connections
- Application domains
- Surprising/tangential connections worth noting
Return a thematic map of your library's coverage of this topic.
How to Launch Agents (Claude Code Only)
Use the Task tool with subagent_type="general-purpose":
Task(
description="Comprehensive Zotero search for X",
subagent_type="general-purpose",
prompt="[Use one of the task patterns above]"
)
PART 3: Universal Search Strategy
Multi-Method Search Approach
ALWAYS use multiple search methods in combination (in both environments):
A. Semantic Search (Primary for Conceptual Discovery)
- Use
zotero_semantic_search for conceptual, thematic, or exploratory queries
- Try multiple phrasings of the same concept
- Use natural language descriptions, not just keywords
- Example variations:
- "theories of embodied cognition"
- "how body influences thought and reasoning"
- "physical experience shapes cognitive processes"
- Claude Desktop: limit=10
- Claude Code (agents): no limit restriction
B. Keyword Search (Complementary)
- Use
zotero_search_items with multiple keyword variations
- Try synonyms, related terms, broader/narrower terms
- Use different word forms (singular/plural, verb/noun)
- Example variations for "reading comprehension":
- "reading comprehension"
- "text understanding"
- "literacy"
- "comprehension strategies"
C. Advanced Search (Targeted)
- Use
zotero_advanced_search for precise criteria
- Combine multiple fields (author + keyword, year + tag)
- Use for filtering after broader searches
D. Tag & Collection Filtering
- Use
zotero_get_tags to discover relevant tags
- Use
zotero_search_by_tag with multiple tag variations
- Use
zotero_get_collections and zotero_get_collection_items for organized searches
E. Full-Text & Annotations
- Use
zotero_search_notes to search annotations and highlights
- Use
zotero_get_item_fulltext for content not in metadata
- Critical for finding concepts mentioned in text but not in titles/abstracts
Common Search Patterns
Pattern: "Find me papers about X"
Claude Desktop:
1. zotero_semantic_search: "X" (limit=10)
2. zotero_semantic_search: "X alternative phrasing" (limit=10)
3. zotero_search_items: keyword variations of X (limit=10)
4. zotero_get_tags: look for X-related tags
5. zotero_search_by_tag: if relevant tags found (limit=10)
6. zotero_search_notes: "X" (limit=10)
Result: ~50+ results safely retrieved
Claude Code:
Launch agent with Task tool (Pattern 1)
Agent performs comprehensive multi-strategy search
Returns curated results with synthesis
Pattern: "What do I have on [author]?"
Claude Desktop:
1. zotero_search_items: author="[Author]" (limit=10)
2. zotero_advanced_search: author + recent years (limit=10)
3. zotero_search_notes: "[Author]" (limit=10)
4. zotero_semantic_search: "[Author]'s main concepts" (limit=10)
Claude Code:
Launch agent with Task tool (Pattern 2)
Search Failure Recovery
If initial searches yield poor results:
-
Ask clarifying questions:
- "Are you looking for theoretical or empirical work?"
- "Any specific time period or authors?"
- "Is this about methodology, findings, or theory?"
-
Broaden search:
- Use more general terms
- Remove filters
- Try related fields/disciplines
-
Check search database status:
- Use
zotero_get_search_database_status
- Suggest
zotero_update_search_database if outdated
-
Try alternative angles:
- If searching for method, search for problems it solves
- If searching for theory, search for phenomena it explains
- If searching for author, search for concepts they study
PART 4: Bibliography Output Formatting
When the user requests a bibliography or formatted output of search results:
Logseq Formatting Standards
ALWAYS use outline hierarchy (nested bullet points), NEVER use markdown headers (#):
NO BOLD STYLING - use plain text for all content
Compact citation format:
- Main Topic - Bibliography
- A. Category Name
- Author(s), Year. Title (English Translation if applicable)
- Type: Article Type
- Journal: Journal Name, Volume X, Issue Y, Pages Z
- Zotero: [zotero://select/library/items/ITEM_KEY](zotero://select/library/items/ITEM_KEY)
- DOI: [if available]
- Abstract (Chinese): [if applicable]
- Abstract (English): [translation or original]
Format rules:
- First line: Author(s), Year. Title (English Translation)
- For Chinese authors: 黃美金 (Huang Mei-Jin)
- For multiple authors: separate with semicolons
- For no date: use "n.d."
- For no author: use institutional name or "N/A"
Translation Requirements
-
Chinese Abstracts:
- Always provide BOTH Chinese original and English translation
- Label clearly as
Abstract (Chinese): and Abstract (English):
- Translate comprehensively, not just summaries
-
Chinese Titles:
- Provide English translation in parentheses after Chinese title
- Format:
中文標題 (English Translation)
- If English title exists in metadata, use that; otherwise translate
-
Author Names:
- Include both Chinese characters and romanization when available
- Format:
黃美金 (Huang Mei-Jin)
Required Metadata Fields
Each bibliography entry must include (when available):
- Title (with translations as needed)
- Authors (with Chinese/romanization)
- Date (YYYY-MM-DD or YYYY)
- Type (Journal Article, Book Chapter, Thesis, etc.)
- Journal/Publication (with volume, issue, pages)
- Zotero link (format:
zotero://select/library/items/ITEM_KEY)
- Abstract (Chinese and/or English as applicable)
- DOI (if available)
What NOT to Include
- ❌ No summary sections at the end of bibliographies (no totals, no "organized by themes" recap)
- ❌ No markdown headers (
#, ##, etc.) - use nested bullets only
- ❌ No bold styling (
**text**) - use plain text throughout
- ❌ No item counts or statistics sections at the end
Bibliography Structure Example
- Indigenous Language Proficiency Certification (原住民族語言能力認證) - Bibliography
- A. Core Certification Papers
- 黃美金 (Huang Mei-Jin), 2003. 原住民族語言能力認證：回顧與展望 (Indigenous Language Proficiency Certification: Review and Prospects)
- Type: Journal Article
- Journal: 原住民教育季刊, Issue 9, Pages 5-27
- Zotero: [zotero://select/library/items/W44VF3CG](zotero://select/library/items/W44VF3CG)
- Abstract (Chinese): [full Chinese abstract]
- Abstract (English): [full English translation]
- B. Policy & Historical Context
- [next paper...]
File Handling
When creating bibliographies:
- Save to
/Users/niyaro/Desktop/ with descriptive filename
- Use
.md extension
- Open in BBEdit automatically (use
bbedit command)
- Confirm file creation and location to user
PART 5: Tool Quick Reference
| Tool | Primary Use | Claude Desktop Limit | Claude Code (Agent) |
|---|
zotero_semantic_search | Conceptual discovery | limit=10 | No limit, use liberally |
zotero_search_items | Keyword matching | limit=10 | No limit |
zotero_advanced_search | Precise filtering | limit=10 | No limit |
zotero_get_tags | Discover tags | No limit needed | No limit needed |
zotero_search_by_tag | Tag filtering | limit=10 | No limit |
zotero_search_notes | Annotation search | limit=10 | No limit |
zotero_get_annotations | Highlight retrieval | limit=10 | No limit |
zotero_get_item_fulltext | Full-text access | N/A (single item) | N/A (single item) |
zotero_get_collections | Collection discovery | No limit needed | No limit needed |
zotero_get_recent | Recent additions | limit=10 | No limit |
zotero_update_search_database | Update index | N/A | N/A |
Critical Reminders
For Both Environments
- Never use just one search method
- Never try just one search term variation
- Always check tags before searching
- Always search both metadata and full-text/annotations
- Always explain your search path
- Always refine based on initial results
Claude Desktop Specific
- 🚨 SAFETY: Always use limit=10 (max 15-20) to prevent conversation deletion
- 🚨 SAFETY: For comprehensive results, use multiple searches or agents, NOT large limits
Claude Code Specific
- Default to agents for non-trivial searches
- Be comprehensive - no crash limits
- Let agents explore - they can handle complexity autonomously
- Synthesize results - raw lists are not enough
Bibliography Formatting
- Format for Logseq - use outline hierarchy, not headers; NO bold styling
- Compact citation format - Author(s), Year. Title on first line
- Translate Chinese content - provide both original and English versions
Remember: This skill adapts to your environment. In Claude Code, leverage agents for comprehensive autonomous searches. In Claude Desktop, use careful batched searches with safety limits.
