# Zotero Mcp Skill

> Claude Desktop skill for comprehensive, multi-strategy searching of Zotero libraries via MCP server with semantic search

- **Type:** MCP server
- **Install:** `agentstack add mcp-kerim-zotero-mcp-skill`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [kerim](https://agentstack.voostack.com/s/kerim)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [kerim](https://github.com/kerim)
- **Source:** https://github.com/kerim/zotero-mcp-skill

## Install

```sh
agentstack add mcp-kerim-zotero-mcp-skill
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Zotero MCP Search Skill for Claude

A comprehensive, **context-aware** skill that enables advanced, multi-strategy searching of your Zotero library through the Zotero MCP (Model Context Protocol) server. **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. Works intelligently in both **Claude Desktop** and **Claude Code**.

## What This Is

This is a **universal Claude skill** that teaches Claude how to search your Zotero reference library intelligently and comprehensively, adapting to the environment:

- **In Claude Code:** Uses autonomous agents for comprehensive multi-step searches
- **In Claude Desktop:** Uses safe batched searches with conversation crash protection
- **For plain markdown outline format:** Suitable for pasting into Logseq with side-by-side Chinese-English translations

Instead of simple one-off searches, Claude learns to:

- Use **semantic/AI-powered search** to find conceptually related papers
- Try **multiple search angles** with different phrasings and synonyms
- **Combine search methods** (semantic + keyword + tags + full-text + annotations)
- **Iteratively refine** searches based on results
- **Ask clarifying questions** when your query is ambiguous
- **Adapt strategy** based on environment (agents in Code, batching in Desktop)
- **Format as plain markdown outline** with proper structure and translations for Logseq

## Why This Skill Exists

### The Problem

The Zotero MCP server provides powerful semantic search capabilities, but using it effectively requires:
- Understanding multiple search strategies (semantic vs. keyword vs. tag-based)
- Knowing when to use each search method
- Trying multiple variations and phrasings
- Searching across metadata, full-text, notes, and annotations
- **Claude Desktop:** Avoiding response limits that can crash conversations
- **Claude Code:** Leveraging agents for autonomous comprehensive searches

Without guidance, Claude might:
- Use only one search method and miss relevant papers
- Try only one search phrase and return incomplete results
- **In Desktop:** Request too many results at once (causing crashes)
- **In Code:** Not utilize agents for complex multi-step searches
- Not explore alternative search angles

### The Solution

This skill provides Claude with:
- **Environment detection** - Automatically detects Claude Code vs Claude Desktop
- **Mandatory multi-angle search strategies** (minimum 3 semantic + 3 keyword variations)
- **Safe batching guidelines** for Desktop (limit=10 per search to prevent crashes)
- **Agent-based patterns** for Code (comprehensive autonomous searches)
- **Comprehensive search patterns** combining multiple methods
- **Iterative refinement workflows** to improve results
- **Plain markdown outline formatting** suitable for Logseq with Chinese/English translation support

## Features

### Core Capabilities

- **Context-Aware Operation:** Detects environment and adapts search strategy
  - **Claude Code:** Launches autonomous agents for multi-step comprehensive searches
  - **Claude Desktop:** Uses safe batched searches with crash protection
- **Semantic-First Discovery:** AI-powered conceptual search to find related work
- **Multi-Strategy Search:** Combines semantic, keyword, tag-based, and full-text methods
- **Iterative Refinement:** Analyzes initial results and refines search strategy
- **Safety-First Design:** Built-in protections against Claude Desktop crash bugs
- **Comprehensive Coverage:** Searches metadata, full-text PDFs, annotations, and notes
- **Logseq Integration:** Formats bibliographies for Logseq with proper outline hierarchy
- **Translation Support:** Handles Chinese-English bilingual content

### Search Methods Taught

1. **Semantic Search** - Conceptual similarity using AI embeddings
2. **Keyword Search** - Traditional text matching with variations
3. **Advanced Search** - Multi-criteria filtering (author + keyword + year)
4. **Tag Search** - Leverage your existing Zotero tags
5. **Full-Text Search** - Search within PDF contents
6. **Annotation Search** - Find your highlights and notes
7. **Collection Search** - Navigate your Zotero collections

### Environment-Specific Features

#### Claude Code
- **Agent-Based Searches:** Autonomous multi-step search execution
- **No Limit Restrictions:** Can retrieve comprehensive results safely
- **Parallel Searches:** Multiple search strategies executed simultaneously
- **Intelligent Synthesis:** Agents deduplicate and prioritize results

#### Claude Desktop
- **Safe Batching:** limit=10 per search to prevent crashes
- **Iterative Presentation:** Progressive result display with user confirmation
- **Multi-Angle Coverage:** Multiple small searches instead of large ones
- **Crash Protection:** Built-in safeguards against conversation deletion

### Output Formatting Features

- **Plain Markdown Outline:** Nested bullets (no markdown headers), suitable for pasting into Logseq
- **Compact Citations:** Author(s), Year. Title format
- **No Bold Styling:** Plain text throughout
- **Chinese-English Support:** Side-by-side titles and abstracts for improved English search
- **Automatic Translation:** English translations of Chinese content
- **Zotero Links:** Clickable zotero:// URLs for each item
- **Thematic Organization:** Grouped by categories (no summary sections)

## Installation

### Prerequisites

1. **Zotero Desktop** with your reference library
2. **Zotero MCP Server** installed and configured
   - Repository: https://github.com/54yyyu/zotero-mcp
   - Follow their installation instructions
3. **Claude Desktop** and/or **Claude Code** with MCP support
4. The Zotero MCP server configured in your Claude MCP settings

### Installing This Skill

#### For Claude Desktop

1. Download the [latest release](../../releases) zip file
2. Open Claude Desktop
3. Go to Settings → Skills
4. Click "Import Skill" and select the downloaded zip file

#### For Claude Code

1. Clone or download this repository
2. Copy the skill folder to `~/.claude/skills/zotero-mcp/`
3. Restart Claude Code or reload skills

#### Manual Installation

1. Clone or download this repository:
   ```bash
   git clone https://github.com/kerim/zotero-mcp-skill.git
   ```
2. Copy the `SKILL.md` file to your Claude skills directory
3. Restart Claude or reload skills

## Usage

### When Claude Uses This Skill

Claude automatically activates this skill when you need to:
- Search your Zotero library for papers or references
- Explore a research topic in your collection
- Find related work on a concept or theme
- Locate specific authors or papers
- Search through your annotations and notes
- Generate formatted bibliographies for Logseq

### Example Queries

**Conceptual Discovery:**
```
"Find papers about embodied cognition"
```
- **Claude Code:** Launches agent → comprehensive multi-strategy search → curated results
- **Claude Desktop:** Multiple semantic/keyword/tag searches (limit=10 each) → combined results

**Author Search:**
```
"What do I have by Susan Carey?"
```
- **Claude Code:** Agent searches author + citations + concepts
- **Claude Desktop:** Batched searches by author + notes + semantic concepts

**Complex Topic:**
```
"Research about skill transfer in mathematical reasoning"
```
- **Claude Code:** Agent cross-references multiple concepts → thematic synthesis
- **Claude Desktop:** Combined semantic/keyword searches → manual synthesis

**Bibliography Generation:**
```
"Create a Logseq bibliography for all papers on Indigenous language policy"
```
→ Claude searches comprehensively → retrieves metadata → formats with:
  - Logseq outline hierarchy (no headers)
  - Compact citations (Author, Year. Title)
  - Chinese/English bilingual support
  - No bold styling
  - Zotero links

### Search Patterns You'll See

#### Claude Code
1. **Analyze query** → Detect search type
2. **Launch agent** → Autonomous comprehensive search
3. **Agent executes** → Multiple strategies in parallel
4. **Agent synthesizes** → Deduplication and prioritization
5. **Present findings** → Curated results with context

#### Claude Desktop
1. **Analyze query** → Determine approach
2. **Execute batched searches** → 5-10 searches with limit=10
3. **Combine results** → Merge and deduplicate
4. **Refine if needed** → Alternative angles for poor results
5. **Present findings** → Results with search path explanation

## Search Philosophy

This skill enforces a **"search comprehensively, not narrowly"** philosophy:

### Core Principles

- **Never settle for one search** - Always try multiple angles
- **Never use one search term** - Always try variations and synonyms
- **Always combine methods** - Semantic + keyword + tags + full-text
- **Always check tags first** - Discover user's tagging conventions
- **Always refine iteratively** - Analyze results and adjust strategy
- **Always ask when unclear** - Clarifying questions for vague queries
- **Adapt to environment** - Use agents in Code, batching in Desktop

### Minimum Search Requirements

For any user query, Claude will try AT MINIMUM:
- 3 semantic search variations (different phrasings)
- 3 keyword variations (synonyms, related terms)
- 1 tag search (after checking available tags)
- 1 full-text/annotation search (if applicable)

## Configuration

### Customization

You can customize this skill by editing `SKILL.md`:

- Modify default search limits (Claude Desktop: currently limit=10)
- Add domain-specific search patterns
- Adjust search variation requirements
- Add custom presentation preferences
- Customize markdown outline formatting rules
- Adjust agent prompts (Claude Code only)

### Search Database

The skill will check and update your Zotero semantic search database when needed using:
- `zotero_get_search_database_status` - Check database status
- `zotero_update_search_database` - Update with latest items

## Technical Details

### MCP Tools Used

This skill teaches Claude to use these Zotero MCP server tools:

| Tool | Purpose | Desktop Limit | Code (Agent) |
|------|---------|---------------|--------------|
| `zotero_semantic_search` | AI-powered conceptual search | 10 | No limit |
| `zotero_search_items` | Keyword matching | 10 | No limit |
| `zotero_advanced_search` | Multi-criteria filtering | 10 | No limit |
| `zotero_get_tags` | Discover available tags | - | - |
| `zotero_search_by_tag` | Tag-based filtering | 10 | No limit |
| `zotero_search_notes` | Search annotations/notes | 10 | No limit |
| `zotero_get_annotations` | Retrieve highlights | 10 | No limit |
| `zotero_get_item_fulltext` | Access full-text content | - | - |
| `zotero_get_item_metadata` | Retrieve item metadata | - | - |
| `zotero_get_collections` | List collections | - | - |
| `zotero_get_recent` | Recent additions | 10 | No limit |

### Safety Mechanisms

#### Claude Desktop
1. **Hard limit defaults** - All searches use limit=10 by default
2. **Batched iteration** - Multiple small searches instead of large ones
3. **Interactive fallback** - Progressive result presentation
4. **Crash prevention** - Never exceeds limit=20 in a single call

#### Claude Code
1. **Agent sandboxing** - Agents run searches independently
2. **Parallel execution** - Multiple searches simultaneously
3. **Intelligent synthesis** - Agents deduplicate and prioritize
4. **No conversation risk** - Agents don't cause UI crashes

## Troubleshooting

### "No results found"

Claude will:
- Try broader search terms
- Use more general concepts
- Remove filters
- Search related fields/disciplines
- Ask clarifying questions

### "Search database outdated"

Claude will suggest:
```
zotero_update_search_database
```

### "Too many/few results"

Claude will automatically:
- **Too many:** Add filters (tags, date ranges, collections)
- **Too few:** Broaden terms, try synonyms, search alternative angles

### "Claude Desktop crashed during search"

If you experience conversation deletion:
- The skill enforces limit=10 by default to prevent this
- Ensure you're using the latest version of this skill
- Report persistent issues to both this repo and Zotero MCP server

## Contributing

Contributions welcome! To improve this skill:

1. Fork this repository
2. Make your changes to `SKILL.md`
3. Test with both Claude Desktop and Claude Code
4. Submit a pull request

### Ideas for Contributions

- Domain-specific search patterns (medical, legal, etc.)
- Additional search failure recovery strategies
- Integration with other Zotero MCP features
- Result presentation templates
- Language-specific search variations
- Additional markdown outline formatting styles
- More agent task patterns

## Related Projects

- **Zotero MCP Server:** https://github.com/54yyyu/zotero-mcp
- **Model Context Protocol:** https://modelcontextprotocol.io/
- **Claude Desktop:** https://claude.ai/download
- **Claude Code:** https://docs.claude.com/claude-code

## License

MIT License - see [LICENSE](LICENSE) file for details

## Acknowledgments

- Built for the [Zotero MCP Server](https://github.com/54yyyu/zotero-mcp) by @54yyyu
- Developed for Claude Desktop and Claude Code
- Semantic search powered by Claude's embedding models

## Support

- **Issues:** [GitHub Issues](../../issues)
- **Discussions:** [GitHub Discussions](../../discussions)
- **Zotero MCP Server Issues:** https://github.com/54yyyu/zotero-mcp/issues

---

**Made for researchers who want comprehensive, intelligent search of their Zotero libraries - whether in Claude Desktop or Claude Code.**

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [kerim](https://github.com/kerim)
- **Source:** [kerim/zotero-mcp-skill](https://github.com/kerim/zotero-mcp-skill)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-kerim-zotero-mcp-skill
- Seller: https://agentstack.voostack.com/s/kerim
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.