zotero-rag
Provides tools for searching a local Zotero library's full-text PDFs, including hybrid vector/BM25 search with filters for year, author, tag, collection, and type; searching within a single item; retrieving surrounding context; getting bibliographic metadata and abstracts; listing items; checking index status; and updating the index.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@zotero-rag Search my library for XAI in Alzheimer's diagnosis and cite the pages."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
zotero-rag — Twoja biblioteka Zotero jako narzędzie dla Claude (MCP)
Własny, odchudzony pipeline RAG inspirowany RAG-Assistant-for-Zotero (kod napisany od nowa). Serwer MCP przeszukuje pełne teksty PDF z Zotero, a odpowiedź z cytowaniami pisze Claude (Desktop lub Code). Nie trzeba klucza API. Wszystko liczy się lokalnie.
Pipeline
zotero.sqlite (kopia, tylko odczyt) ──► PDF (PyMuPDF)
──► czyszczenie: nagłówki/stopki, dzielenie wyrazów, ligatury, bibliografia pomijana
──► fragmenty ~1000 znaków ze zdań w obrębie sekcji (+ abstrakt z Zotero)
──► embeddingi bge-m3 (wielojęzyczne: PL+EN, zapytanie PL znajduje tekst EN)
──► data/index.sqlite: wektory + FTS5/BM25 (bez polskich znaków diakrytycznych też działa)
zapytanie ──► wektory (cosine) + BM25 (z dopasowaniem prefiksów pod polską fleksję)
──► RRF ──► reranker bge-reranker-v2-m3 ──► max N fragmentów na pracę
──► Claude: odpowiedź z cytatami (Nazwisko, rok, s. X)Pliki: zotero_rag/zotero.py (Zotero), pdftext.py (PDF→fragmenty), store.py (indeks),
models.py (modele), search.py (wyszukiwanie), indexer.py, server.py (narzędzia MCP), cli.py.
Related MCP server: Stratosphere MCP Zotero
Użycie
git clone https://github.com/jolapodolszanska/zotero-rag.git
cd zotero-rag
uv sync # instalacja zależności
uv run zotero-rag index # indeksuj nowe/zmienione PDF-y (--full: od zera)
uv run zotero-rag search "redukcja artefaktów w CBCT" # test z terminalaPodłączenie do Claude Code
claude mcp add zotero --scope user "C:\ścieżka\do\zotero-rag\.venv\Scripts\zotero-rag.exe" serve(macOS/Linux: .venv/bin/zotero-rag.)
(W PowerShellu nie używaj wariantu z -- uv --directory ...: PowerShell zjada -- i claude
zgłasza unknown option '--directory'.)
Podłączenie do Claude Desktop
%APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"zotero": {
"command": "uv",
"args": ["--directory", "C:\\ścieżka\\do\\zotero-rag", "run", "zotero-rag", "serve"]
}
}
}Po restarcie Claude zapytaj np. „Co moja biblioteka mówi o wyjaśnialności (XAI) w diagnostyce Alzheimera? Cytuj strony.”
Narzędzia MCP
narzędzie | do czego |
| wyszukiwanie hybrydowe; filtry: lata, autor, tag, kolekcja, typ |
| szukanie w jednej pracy |
| sąsiednie fragmenty (gdy cytat jest urwany) |
| pełny opis bibliograficzny + abstrakt |
| lista prac (z filtrami) |
| statystyki, kolekcje, tagi |
| doindeksowanie nowych PDF-ów |
Ustawienia (zmienne środowiskowe)
zmienna | domyślnie |
|
|
| — (folder bazowy dla plików „linked”) |
|
|
|
|
|
|
| — (np. |
Inne modele dobre dla polskiego: sdadas/mmlw-roberta-large (prefiks zapytania zapytanie: ),
intfloat/multilingual-e5-large (prefiksy query: / passage: ). Lżejszy i szybszy na CPU:
intfloat/multilingual-e5-base.
PDF-y muszą mieć warstwę tekstową (skany bez OCR zostaną pominięte i zgłoszone w logu).
Licencja
MIT, zob. LICENSE. Pomysł zaczerpnięty z RAG-Assistant-for-Zotero (GPL-3.0); kod tego repozytorium został napisany od nowa.
Available Tools
7 toolsget_contextC
Passages around passage seq of a work, in reading order (seq comes from search results).
Inputs: seq (required), item_key (required), after, before. Returns: result
get_itemB
Full bibliographic record of one work: authors, year, venue, DOI, tags, collections, abstract.
Inputs: item_key (required). Returns: result
index_statusA
How many works and passages are indexed, with which model, plus collections and top tags.
Inputs: no named parameters. Returns: result
list_itemsB
List indexed works (optionally filtered), one per line: item_key, citation, title.
Inputs: tag, author, year_to, year_from, +1 more. Returns: result
search_libraryA
Hybrid semantic + keyword search over the full text of PDFs in the Zotero library.
Returns the best matching passages with author, year, title, page and a zotero:// link. query: what to look for, in Polish or English (searching both languages often helps). author/tag/collection: case-insensitive substring match. item_type: e.g. journalArticle, book, thesis. per_item: max passages per work (raise it when studying a single source).
Inputs: query (required), tag, limit, author, +5 more. Returns: result
search_within_itemB
Search inside one work only (item_key from search results or list_items).
Inputs: query (required), item_key (required), limit. Returns: result
update_indexA
Index PDFs added or changed in Zotero since the last run (can take a few minutes for many new files).
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool targets a distinct retrieval concern: library-wide search, single-item search, context expansion, metadata, listing, status, and indexing. The only mild overlap is search_library vs search_within_item, but their descriptions clearly delineate scope (whole library vs one work).
All names are snake_case and mostly follow a verb_noun pattern (search_library, get_item, list_items, update_index). The lone noun_phrase outlier is index_status, a minor deviation that remains readable and predictable.
Seven tools is well-scoped for a RAG search server, with each tool earning its place across search, retrieval, metadata, and index management. Nothing feels redundant or padded.
The surface covers the core lifecycle: search, context expansion, metadata retrieval, listing, status, and index updates. Minor gaps exist (e.g., no per-item deletion or citation export), but these are workarounds rather than dead ends for typical workflows.
Maintenance
Related MCP Connectors
Zotero MCP server for Claude and ChatGPT: search, citations, safe writes, PDF passages and pages.
Academic literature search, retrieval, and private library management on top of OpenAlex.
Search arXiv/Semantic Scholar/OpenAlex + medical evidence (PubMed/Europe PMC) + LaTeX/PDF tools.
Your versioned prompt library: search, read, save and version prompts from Claude Code.
Related MCP Servers
- AlicenseAqualityBmaintenanceConnects your Zotero research library with Claude and other AI assistants via the Model Context Protocol, allowing you to search your library, access content, discuss papers, get summaries, and analyze citations.3511,253 PyPI5,941MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language interaction with Zotero libraries, allowing users to search, retrieve, and update papers and metadata via AI assistants like Claude and Gemini.1GPL 2.0
- AlicenseNot gradedqualityCmaintenanceConnects Zotero to Claude Desktop, allowing Claude to read, search, and organize a user's Zotero library through local and web APIs.1MIT
- AlicenseAqualityCmaintenanceEnables Claude to search, retrieve, and cite from your Zotero library, including local databases and zotero.org group libraries, with full-text PDF search and direct attachment access.23MIT