nicsuzor/zotmcp

ZotMCP

MCP server for semantic search and literature review across a shared Zotero academic library.

Features

• Semantic Search - Vector-based search across library items
• Citation Retrieval - Get properly formatted academic citations
• Similar Items - Find related works by similarity
• Author Search - Find all works by specific authors
• 7 Specialized Tools - Search, retrieve, and analyze academic literature

Available Tools

Zotero Library Search Tools

1. search - Semantic search across YOUR Zotero library (primary tool)
2. get_item - Retrieve full text and metadata by Zotero key
3. get_similar_items - Find works similar to a given item
4. get_collection_info - Library statistics and metadata

OpenAlex Discovery Tools

5. search_openalex_author - Discover papers by author from OpenAlex (240M+ papers, NOT your library)
6. search_papers - Search OpenAlex for new papers beyond your library
7. get_paper_citations - Get forward citations for a paper from OpenAlex
8. get_referenced_works - Get backward citations for a paper from OpenAlex

Setup

If you have docker AND gcloud installed already

1. Get access: Contact Nic with your Google email

2. Just add this to your list of MCP servers:

    "zotmcp": {"type": "stdio","command": "docker","args": ["run","--rm","-v","/home/$USER/.config/gcloud:/root/.config/gcloud:ro","-i","us-central1-docker.pkg.dev/prosocial-443205/reg/zotmcp:latest"]}

Normal setup

1. Get access:

   First, contact Nic with your Google email.

   Then, login with your Google credentials:

   gcloud auth application-default login
   

2. Install uv: Windows:

   winget install --id=astral-sh.uv -e
   

   Linux:

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

3. Restart terminal (required for PATH changes)

4. Download vectors (~8GB):

   uvx --from git+https://github.com/nicsuzor/zotmcp.git zotmcp-download
   

5. Add to Claude:

   For Claude Code:

   claude mcp add-json zot '{"command":"uvx","args":["--from","git+https://github.com/nicsuzor/zotmcp.git","zotmcp"]}'
   

   For Claude Desktop:

   Add to claude_desktop_config.json:

   {
     "mcpServers": {
       "zot": {
         "command": "uvx",
         "args": ["--from", "git+https://github.com/nicsuzor/zotmcp.git", "zotmcp"]
       }
     }
   }
   

Config location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Architecture

ZotMCP is an MCP (Model Context Protocol) server that provides semantic search and literature review capabilities for a shared Zotero academic library.

• Zotero Library: prosocial group library
• ChromaDB Collection: prosocial_zot
• Embedding Model: Google gemini-embedding-001 (3072 dimensions)

The ChromaDB is created by the Buttermilk vectorization pipeline.

• Full text sourced from Zotero group first
• Where full text is not available, we extract full text from source PDF
• Each source is chunked using a semantic splitter into approximately 1000 tokens, with overlap of 250 tokens.
• Citations are generated by a LLM based on the first page of full text in the format: Authors (Year). Title. Outlet

Local Development requirements

The vectorization pipeline requires poppler-utils for PDF text extraction:

sudo apt-get install poppler-utils

Note: This is only required for local development when running the vectorization pipeline. The Docker image already includes this dependency.