Zayit MCP Server

An MCP (Model Context Protocol) server that exposes the Zayit Jewish texts library to AI assistants. Wraps Zayit's SQLite database and Lucene search indices — no network required, fully offline.

Prerequisites

• Zayit installed on the same machine (provides the database and Lucene indices)
• Java 21+ — required by Lucene 10.x

Installing Java 21

Building

The Gradle wrapper is included — no separate Gradle installation needed.

# Linux / macOS
chmod +x gradlew
./gradlew shadowJar

# Windows
gradlew.bat shadowJar

Output: build/libs/zayit-mcp.jar (~35 MB, self-contained)

Running

stdio mode (for Claude Desktop / MCP clients)

# Linux / macOS
chmod +x run-stdio.sh
./run-stdio.sh

# Windows
run-stdio.bat

HTTP / SSE mode (for testing or remote access)

# Linux / macOS
./run-http.sh 3001

# Windows
run-http.bat 3001

The MCP endpoint is at http://localhost:3001/mcp.

Custom data directory

If Zayit stores its data somewhere non-standard, set ZAYIT_DATA_DIR:

ZAYIT_DATA_DIR=/path/to/databases ./run-stdio.sh

Data paths (auto-detected per OS)

Claude Desktop configuration

Windows

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "zayit": {
      "command": "C:\\path\\to\\zayit-mcp\\run-stdio.bat"
    }
  }
}

macOS / Linux

~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
~/.config/Claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "zayit": {
      "command": "/path/to/zayit-mcp/run-stdio.sh"
    }
  }
}

Tools

search_books

Search for books by title using SQLite LIKE.

Returns: id | title | category | lines=N [primary]

Example: query="בראשית" → בראשית, בראשית רבה, אגדת בראשית …

search_ref

Fast prefix lookup via the Lucene reference index.

Returns: book_id=N | title

get_text

Retrieve lines from a book by numeric ID with pagination.

get_text_by_ref

Retrieve text by Hebrew reference string — the ergonomic alternative to get_text.

Returns: Matched line (marked ►) with surrounding context, across all books containing that reference.

Example: ref="בראשית א, א" finds Genesis 1:1 in the base text plus every commentary quoting it.

get_book_toc

Get the hierarchical chapter/section table of contents for a book.

Returns: Indented TOC with line_id pointers per section. Use the line_id values as offset in get_text.

Example output:

▸ בראשית → line_id=1
  • פרק א → line_id=2
  • פרק ב → line_id=34
  ...

get_links

Cross-references for a book or specific line, from the link table.

Returns: Source and target refs with 120-char text snippets and connection type.

text_search

Full-text search across all ~6,000 books using Lucene. Nikud and teamim are stripped automatically; final letters (ך→כ, ם→מ, ן→נ, ף→פ, ץ→צ) are normalized.

Lucene query syntax:

Architecture

AI client
    │  MCP JSON-RPC (stdio or HTTP/SSE)
    ▼
zayit-mcp.jar
    ├── SQLite (seforim.db)          → search_books, get_text, get_text_by_ref,
    │                                   get_book_toc, get_links
    └── Lucene (seforim.db.lucene,   → text_search, search_ref
                seforim.db.lookup.lucene)

Stack: Kotlin 2.3 · MCP SDK 0.12.0 · Lucene 10.3.2 · SQLite JDBC 3.49 · Ktor 3.1 (HTTP mode)