sacred-texts-mcp

A local Model Context Protocol server for semantic search, close-reading, and cross-tradition comparison across sacred, mythological, and foundational texts.

It turns heterogeneous source material into citable textual units, embeds them in a filtered vector index, and gives AI clients seven focused tools for retrieval and textual analysis.

What you can do

• Search passages by meaning across multiple traditions and works.

• Find cross-cultural parallels starting from a known passage.

• Retrieve complete, citable passages instead of isolated search snippets.

• Search exact words, lemmas, and Strong numbers where lexical data exists.

• Inspect original-language tokens, morphology, and translation alignment.

• Discover which works are available and what kind of analysis each supports.

Example questions:

Where do flood narratives appear across different traditions?

Which creation passages resemble Genesis 1:1?

How is a specific Hebrew or Greek lemma used across the indexed texts?

See real tool output from three example sessions.

Related MCP server: textual-criticism-mcp

How it works

flowchart LR
    A[Heterogeneous sources] --> B[Format-aware parsers]
    B --> C[Citable text units]
    C --> D[Gemini embeddings]
    D --> E[(SQLite + sqlite-vec)]
    E --> F[FastMCP server]
    F --> G[Codex, Claude Code, or another MCP client]

The index is local and distributed as a single SQLite file. No API key is needed to search the prebuilt public index. A Gemini API key is required only if you choose to rebuild its embeddings.

For implementation details, see Architecture and Normalization.

MCP tools

Quick start

1. Install

Requirements: Git and Python 3.10 or newer.

git clone https://github.com/alessandrodalpozzo/sacred-texts-mcp.git
cd sacred-texts-mcp
python -m pip install -r requirements.txt

On Windows, use py -3 instead of python if Python is installed through the Windows launcher.

2. Download the prebuilt index

Download index-open.db from the latest release and save it locally as:

data/index.db

The names differ intentionally: index-open.db is the downloadable release asset; data/index.db is the path expected by the server.

PowerShell:

Invoke-WebRequest `
  -Uri "https://github.com/alessandrodalpozzo/sacred-texts-mcp/releases/latest/download/index-open.db" `
  -OutFile "data/index.db"

macOS or Linux:

curl -L \
  https://github.com/alessandrodalpozzo/sacred-texts-mcp/releases/latest/download/index-open.db \
  -o data/index.db

3. Connect an MCP client

Codex

The project-scoped .codex/config.toml registers the server automatically. Open the repository as a trusted project, restart Codex, and check Settings > MCP servers or run /mcp.

Codex reads the project instructions from AGENTS.md.

Claude Code

Claude Code discovers the committed .mcp.json automatically. Its one-line CLAUDE.md imports AGENTS.md, so Claude and Codex follow the same project guidance.

You can also register the server manually:

claude mcp add sacred-texts -- python /absolute/path/to/sacred-texts-mcp/server/mcp_server.py

Other MCP clients

Configure a standard stdio server with:

{
  "command": "python",
  "args": ["/absolute/path/to/sacred-texts-mcp/server/mcp_server.py"]
}

Rebuilding the index

The repository includes the compressed open corpus, so a rebuild does not require downloading the original source collection:

cp .env.example .env
# Add GEMINI_API_KEY to .env
python index/build_index.py

Rebuilding is optional. The released index is ready for local retrieval.

Engineering highlights

• Format-aware ingestion: reusable parsers normalize TSV, TEI XML, JSON, HTML, OCR-derived text, PDFs, and Wikisource material.

• Citation-preserving chunking: retrieval units follow each work's own verse, section, chapter, or tablet structure rather than arbitrary character windows.

• Incremental embedding pipeline: unchanged units are detected and are not embedded again.

• Native filtered vector search: work and tradition metadata participate directly in SQLite vector retrieval.

• Self-correcting tool interface: ambiguous work or tradition names return candidates that an MCP client can use to refine its request.

• License-aware publishing: the public export is mechanically restricted to works approved for redistribution.

• Automated verification: tests cover corpus schemas, indexing, query behavior, vocabulary resolution, diffing, and public-export enforcement.

Documentation

Scope and limitations

The public artifacts include only openly licensed or public-domain material. They are a curated subset of the editions supported by the ingestion pipeline, not a comprehensive library of every sacred or ancient text.

Semantic similarity is a retrieval aid, not a historical or theological judgment. Results depend on the available edition, translation, and embedding quality. Some works are translation-only and therefore do not support word-level analysis.

This project applies the same neutral retrieval interface to every tradition and does not endorse a theological interpretation. See Data sources and licensing for the exact public scope.

License

The source code is released under the MIT License. Textual data retains its original per-work license and attribution as recorded in data/work_licenses.tsv.