Open English Translation (OET) MCP Server

An official Model Context Protocol (MCP) server providing Large Language Models (LLMs) with high-speed, structured access to the Open English Translation (OET) of the Bible.

What Makes the OET Different?

1. Dual-Stream Parallel Translation:
   • Readers' Version (OET-RV): Natural, idiomatic, thought-for-thought modern English designed for macro-level discourse comprehension and fluency.
   • Literal Version (OET-LV): Transparent, hyper-literal formal equivalence showing every added copula, article, transitive direct object, and untranslated particle.
2. Word-Level Lexical Graph & Interlinear:
   • Every word token is cross-linked via TSV datasets to Hebrew/Aramaic (UHB) and Greek (SR-GNT) dictionary entries, lemmas, Strong's numbers, morphological tags, and canonical gloss distributions.
3. Explicit Translation Decision Tags (\add):
   • Encodes the exact reason for every addition or divergence (@ for referent replacements, ≈ for rewordings, # for number changes, % for speech shifts, ^ for opposite phrasing, ? for uncertainty, ≈/^/→ for Hebrew poetic parallelism, and ⇔ for clause re-ordering).

Quick Start

Running via uvx

uvx oet-mcp-server

Installation from Source

Note: the 191 MB corpus database is a Git-LFS file. Without git lfs pull you get only a ~130-byte LFS pointer, and every data tool fails at runtime.

git clone https://github.com/Freely-Given-org/open-english-translation-mcp-server.git
cd open-english-translation-mcp-server
git lfs install && git lfs pull   # materialize the real corpus database
uv sync
uv run oet-mcp-server

AI Client Configuration

1. Claude Desktop / Antigravity / Cursor

Add to your claude_desktop_config.json or MCP settings:

{
  "mcpServers": {
    "oet-bible": {
      "command": "uvx",
      "args": ["oet-mcp-server"]
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "oet-bible": {
      "command": "uv",
      "args": [
        "--directory",
        "/srv/FreelyGiven/open-english-translation-mcp-server",
        "run",
        "oet-mcp-server"
      ]
    }
  }
}

MCP Server Capabilities

1. Resources & Resource Templates

2. Tools

get_passage

Retrieve scripture in parallel side-by-side, readers, literal, or interlinear table view.

• Arguments:
  • reference (string, required): e.g. "John 1:1-5", "Rom 8:28", "Gen 1:1".
  • version (string): "parallel", "rv", "lv", or "interlinear".
  • include_notes (bool): Attach translator footnotes (TD:, TC:) and cross-references.
  • format (string): "markdown" or "json".
  • show_decision_codes (bool): Reveal inline decision tags ([@referent], [≈rewording]).

compare_translations

Calculates a granular comparative breakdown between OET-RV and OET-LV for a passage.

• Arguments:
  • reference (string, required): e.g. "John 1:1-3", "Romans 1:16-17".

search_text

High-speed full-text search across RV and LV using SQLite FTS5.

• Arguments:
  • query (string, required): e.g. "true light", "covenant".
  • version (string): "both", "rv", or "lv".
  • testament (string): "all", "OT", or "NT".
  • limit (int): Max results (default 20).

search_lemma

Concordance lookup showing how an original Hebrew/Greek root or Strong's ID is translated across the entire Bible.

• Arguments:
  • lemma_or_strongs (string, required): e.g. "logos", "G3056", "bereshit", "H7225".
  • testament (string): "all", "OT", "NT".
  • limit (int): Max sample occurrences.

lookup_word

Drill down into a specific original word link token with complete grammatical parsing and manuscript collations.

• Arguments:
  • word_id (string, required): e.g. "JHNc1v1w5", "MAT_1:1w1".

get_lexicon_entry

Retrieve dictionary definition, semantic domain, and canonical distribution for a lemma or Strong's ID.

• Arguments:
  • query (string, required): Lemma or Strong's ID.
  • lang (string): "auto", "greek", "hebrew".

get_translation_decisions

Isolates all explicit \add decision codes in a passage.

• Arguments:
  • reference (string, required): e.g. "John 1:1-18".

3. MCP Prompts

• comparative_exegesis: Guided prompt leading an AI through rigorous exegesis (macro discourse in RV, micro syntax in LV, and root word studies).
• biblical_word_study: Guided prompt performing a complete biblical word study across genres and testaments.
• translation_critique: Guided prompt analyzing why modern dynamic translations diverge from literal syntax in difficult verses.

OET Translation Decision Codes Reference

Deployment (Docker)

Important: the 191 MB corpus database is stored as a Git-LFS file. A checkout without git lfs pull contains only a ~130-byte LFS pointer, which makes every data tool fail at runtime. The Dockerfile guards against this: scripts/verify_db.py runs at build time and fails the build if the DB isn't a real, queryable SQLite database.

Recommended: use the CI-built image

The .github/workflows/docker-publish.yml workflow materializes the LFS data, builds the image, and pushes it to ghcr.io/freely-given-org/open-english-translation-mcp-server as :latest and :main (on pushes to main) and :v* (on version tags). Deploying servers then pull instead of building:

Before this works, the workflow must have published at least one image (push to main, create a v* tag, or trigger it from the GitHub Actions tab). Until then docker compose pull fails, so use the local-build path below.

git clone --filter=blob:none https://github.com/Freely-Given-org/open-english-translation-mcp-server.git
cd open-english-translation-mcp-server
docker compose pull          # pulls the GHCR image
docker compose up -d         # no local build, no LFS data needed on the server

OET_MCP_IMAGE overrides the image used by docker-compose.yml.

Building locally

git lfs install && git lfs pull   # materialize the real corpus DB
docker compose up -d --build

The container exposes a Docker healthcheck (scripts/healthcheck.py) that validates the DB and that the MCP proxy is accepting connections, so docker inspect / orchestrators report the deploy as unhealthy if the DB is invalid.

License

• Code: Open Source under CC0 1.0 Universal (see the LICENSE file).
• OET Text & Datasets: Creative Commons Attribution-ShareAlike (CC-BY-SA 4.0) by Freely-Given.org.