ptx-mcp

MCP-Server (Model Context Protocol), der Bibeltext direkt aus lokalen Paratext-Projektordnern (USFM-Dateien) liest und als Tools bereitstellt, die ein LLM aufrufen kann.

Unterstützte Beispielanfragen

Wenn der Server installiert ist (siehe unten), kannst du Claude Fragen in natürlicher Sprache stellen – Claude wählt selbst das richtige Tool und die passenden Argumente.

• „Welche Paratext-Projekte habe ich verfügbar?“

• „Welche Bücher sind im WEB-Projekt enthalten?“

• „Zeig mir Genesis 1:1 aus WEB.“

• „Hole Johannes Kapitel 3 aus WEB.“

• „Zeig mir das ganze Buch Jona aus WEB.“

• „Vergleiche Genesis 1:1-5 in WEB und BTBK nebeneinander.“

• „Hole Jakobus 1 aus WEB und BTBK gemeinsam und überspring alle Verse, die in einem von beiden fehlen.“

• „Lies Genesis 1:26 bis 2:3 aus BTBK.“

• „Hat BTBK eine Übersetzung des Johannesevangeliums? Wenn ja, zeig mir Kapitel 1.“

Related MCP server: GetBible MCP

Einschränkungen

• Dieser Code

  • wurde bisher nur sehr begrenzt getestet. Er hat bei mir auf Mac als auch unter Windows funktioniert.

  • wurde bisher nur mit Claude getestet.

  • unterstützt kein Zugriff auf Paratext-Ressourcenprojekte, z. B. RVR80.

• Damit Claude auf diesen stdin-MCP-Server zugreifen kann, muss Claude auf dem lokalen Rechner laufen und nicht in der Cloud.

  • Ich glaube, das bedeutetst du beim Start des Chats die Option „Chat“ wählen und NICHT „Cowork“ wählen musst. Die Cowork-Option scheint (zumindest manchmal?) in einer Cloud-Sandbox zu laufen, die keinen Zugriff auf den lokalen Rechner hat.

Voraussetzungen

• Node.js 18+

  • Ich glaube, das wird automatisch installiert, wenn du Claude Desktop installierst.

• Ein oder mehrere Paratext-Projektordner (jeder mit einer Settings.xml und USFM-Buchdateien)

Einrichtung/Installation

In Claude kann:

• Klicke auf den Button mit deinem Namen in der unteren linken Ecke

• Klicke auf „Settings“

• Klicke auf „Editor“

• Klicke auf „Edit Config“

• Doppelklicke auf „claude_desktop_config.json“, um den Editor zu öffnen

Bearbeite „claude_desktop_config.json“ und füge den Server wie folgt hinzu:

{
  "mcpServers": {
    "ptx-mcp": {
      "command": "npx",
      "args": ["-y", "@milesnl/ptx-mcp"]
    }
  }
  ...
}

WICHTIG! Schließe Claude und starte es neu, um den neuen MCP-Server zu laden.

Das ptx-mcp-Paket wird automatisch aus der NPM-Bibliothek heruntergeladen, wenn du Claude zum ersten Mal einen Paratext-bezogenen Befehl gibst.

Um die Installation zu testen, frage Claude: „Liste Paratext-Projekte auf“.

Fehlerbehebung bei der Installation

• Geh zur du Befehlszeile und probiere „npx -y @milesnl/ptx-mcp“

  • Ein erfolgreicher Ergebnis ist, dass er läuft und dann auf eine Terminaleingabe wartet. Mit Pause Strg+C beenden. Wenn stattdessen Fehlermeldungen angezeigt werden, gibt es einen Grund dafür, dass wir nicht auf das npm-Paket @milesnl/ptx-mcp zugreifen können.

• Nach dem Neustart von Claude kannst unter Settings/Developers nachsehen. Dort sollte ptx-mcp als lokaler MCP-Server angezeigt werden. Thema ergibt, Them Wenn nicht, ist beim Laden etwas schiefgegangen.

• Wenn „ptx-mcp failedinitient“ wird, klicke auf „View Logs“, um zu sehen, warum.

Installationshinweise

den Wenn dein „My Paratext-Ordner“ nicht am Standard-Speicherort C:\My Paratext 9 Projects liegt, wirst du müssen du „args“ anpassen, um diesen Ortsey einzubeziehen.

      "args": ["-y", "@milesnl/ptx-mcp", "/path/to/My Paratext 9 Projects"]

ptx-mcp im Entwicklungsmodus aus dem Quellcode ausführen

Aus dem lokal installierten Quellcode ausführen

• cd /path/to/source

• git clone https://github.com/Nathan22Miles/PtxMCP

• PtxMCP

• npm install

Füge dieszur Konfiguration deines MCP-Clients hinzu (z. B. claude_desktop_config.json).

"mcpServers": {
    "ptx-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "/path/to/PtxMCP"
      ]
    }
  }

Falls du Paratext nicht installiert hast, kannst du „/path/to/source/PtxMCP/myParatextProjects“ zu den args hinzufügen. Dies schafft Zugriff auf das WEB-Projekt.

MCP-Unterstützt Befehle

Hinweis: In den meisten Fällen musst du diese Low-Level nicht kennen. Claude wird deine Anfragen automatisch in dieses Format übersetzen, um auf den MCP zuzugreifen.

list-projects

Listet die Projekt-IDs (Ordnernamen) der Paratext-Projekte auf, die unter dem Projekt-Stammverzeichnis gefunden werden.

list-books

Listet das 3-Buchstaben USFM-Kürzel aller Bücher in einem bestimmten Projekt.

auf.

• project — **Projekt-ID (Ordnername)

get-scripture

Gibt den Vers texte für ein Buch, ein Kapitel oder einen Versbereich aus einem project zurück returniert.

• projects — eine Projekt-ID oder mehrere

• book — 3-Buchstaben USFM-Book-Code (z. B. GEN, MAT, 1CO)

• startChapter / startVerse / endChapter / endVerse — optional; wenn alle vier weggelassen, für das ganze Buch; Weergelaust für ein ganzes Kapitel; oder ein ganzer Bereich (der alle Kapitel umfassen kann)

• allowPartial — wenn true, werden fehlende projects/books/verses stillschweigend weggelassen, statt einen Fehler auszugeben.

Die Ausgabe ist nur der reine Verstext — keine Abschnittsüberschriften, keine Buchtitel, keine Fußnoten, keine Kreuzwortverweise — entfernung ein Vers pro Zeile, formatiert als BOOK CHAPTER:VERSE text.

Wenn mehrere Projekte angefragt werden, wird jede Zeile mit der Projekt-ID präfix iteriert und Verse werden projektweise aneinanderreiht:

WEB GEN 1:1 In the beginning God created the heavens and the earth.
BTBR GEN 1:1 In the beginning, when God began to create all things,

WEB GEN 1:2 The earth was formless and empty ...
BTBR GEN 1:2 the earth did not exist yet, there still was nothing...

Versbrücken im Quelltext (z. B. \v 6-7) werden als einzelneZeile mit der Bezeichnung 6-7 zurückgegeben, nicht doppr per Versnummer.

Entwicklung

npm install
npm run build   # compile TypeScript to dist/
npm test        # run the Vitest suite (uses the myParatextProjects/ fixture data)

Tests lesen Paratext-Projektdaten aus dem Ordner myParatextProjects/.

Danksagungen

Besonderer Dank geht an unfoldingWord für usfm-js, also den USFM-Parser, auf den dieses Projekt aufbaut.

To Do

• Automatische Installation anbietet, z. B. npx @milesnl/ptx-mcp --install

• Mit Gemini CLI usw. testen.