Skip to main content
Glama

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 terminala

Podłą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

search_library

wyszukiwanie hybrydowe; filtry: lata, autor, tag, kolekcja, typ

search_within_item

szukanie w jednej pracy

get_context

sąsiednie fragmenty (gdy cytat jest urwany)

get_item

pełny opis bibliograficzny + abstrakt

list_items

lista prac (z filtrami)

index_status

statystyki, kolekcje, tagi

update_index

doindeksowanie nowych PDF-ów

Ustawienia (zmienne środowiskowe)

zmienna

domyślnie

ZOTERO_DIR

~/Zotero

ZOTERO_BASE_DIR

— (folder bazowy dla plików „linked”)

ZOTERO_RAG_DATA

./data

EMBED_MODEL

BAAI/bge-m3 (zmiana = pełna reindeksacja)

RERANK_MODEL

BAAI/bge-reranker-v2-m3 ("" wyłącza)

EMBED_QUERY_PREFIX / EMBED_DOC_PREFIX

— (np. query: / passage: dla multilingual-e5)

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 tools
get_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

    A3.5/5.0

    Scored across 7 tools

    Disambiguation4/5

    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).

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Connects 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.
      35
      11,253 PyPI
      5,941
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables natural language interaction with Zotero libraries, allowing users to search, retrieve, and update papers and metadata via AI assistants like Claude and Gemini.
      1
      GPL 2.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      23
      MIT