ptx-mcp

ローカルのParatextプロジェクトフォルダ（USFMファイル）から聖書テキストを直接読み取り、LLMが呼び出せるツールとして公開するMCP（Model Context Protocol）サーバーです。

サポートされているプロンプトの例

サーバーをインストールすると（下記参照）、Claudeに自然言語で質問できます。Claudeが適切なツールと引数を自動的に選択します。

• 「利用可能なParatextプロジェクトはどれですか？」

• 「WEBプロジェクトにはどの書がありますか？」

• 「WEBから創世記1章1節を表示して。」

• 「WEBからヨハネによる福音書3章を取得して。」

• 「WEBからヨナ書全体を表示して。」

• 「WEBとBTBKの創世記1章1節から5節を並べて比較して。」

• 「WEBとBTBKの両方からヤコブの手紙1章を取得して、どちらかにない節はスキップして。」

• 「BTBKから創世記1章26節から2章3節を読んで。」

• 「BTBKにヨハネによる福音書の翻訳はありますか？あれば、1章を見せて。」

Related MCP server: GetBible MCP

注意事項

• このコードは

  • これまでのところ、ごく限られたテストしか行われていません。MacとWindowsでは動作しました。

  • Claude Desktopでのみテストされています。

  • Paratextリソースプロジェクト（例：RVR80）へのアクセスには対応していません。

• Claudeがこのstdin MCPサーバーにアクセスするには、Claudeがクラウドではなくローカルマシンで実行されている必要があります。

  • つまり、チャットを開始するときは「Chat」オプションを選択し、「Cowork」オプションは選択しない必要があると思います。 Coworkオプションは（少なくとも場合によっては？）ローカルマシンにアクセスできないクラウドサンドボックスで実行されるようです。

必要条件

• Node.js 18+

  • これはClaude Desktopをインストールすると自動的にインストールされると思います

• ディスク上の1つ以上のParatextプロジェクトフォルダ（各フォルダにSettings.xmlとUSFMブックファイルが含まれていること）

セットアップ/インストール

Claude Desktopで

• 左下隅にある自分の名前のボタンをクリック

• 「Settings」をクリック

• 「Developers」をクリック

• 「Edit Config」をクリック

• エディタを開くには「claude_desktop_config.json」をダブルクリック

以下のようにサーバーを追加するために「claude_desktop_config.json」を編集

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

重要！新しいMCPサーバーを読み込むには、Claudeを閉じて再起動してください。

ptx-mcpパッケージは、ClaudeにParatext関連のコマンドを初めて与えたときに、NPMライブラリから自動的にダウンロードされます。

インストールをテストするには、Claudeに「List Paratext projects」と尋ねてください。

インストールのトラブルシューティング

• コマンドラインで「npx -y @milesnl/ptx-mcp」を実行してみてください

  • 成功すると、実行されてターミナル入力を待ちます。終了するにはControlキーを押しながらCを押します。 代わりにエラーメッセージが表示される場合は、@milesn/ptx-mcp NPMパッケージにアクセスできない何らかの理由があります。

• Claudeを再起動したら、Settings/Developersに移動します。 これにより、ptx-mcpがローカルMCPサーバーとして表示されるはずです。 表示されない場合は、読み込みに問題があります。

• 「ptx-mcp failed」と表示された場合は、「View Logs」をクリックして理由を確認してください。

インストールに関する注意

My Paratextフォルダがデフォルトの場所C:\My Paratext 9 Projectsにない場合は、その場所を含むように「args」を変更する必要があります。

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

開発モードでソースからptx-mcpを実行するには

ローカルにインストールしたソースから実行するには

• cd /path/to/source

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

• cd PtxMCP

• npm install

MCPクライアントの設定（例：claude_desktop_config.json）に追加します。

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

Paratextがインストールされていない場合は、「/path/to/source/PtxMCP/myParatextProjects」をargsに追加できます。これにより、WEBプロジェクトにアクセスできるようになります。

MCPサポートコマンド

注：ほとんどの場合、これらの低レベルコマンドを知る必要はありません。ClaudeはMCPにアクセスするために、あなたのリクエストを自動的にこの形式に変換します。

list-projects

プロジェクトルートの下にあるParatextプロジェクトID（フォルダ名）を一覧表示します。

list-books

指定されたプロジェクトに存在する3文字のUSFMブックコードを一覧表示します。

• project — プロジェクトID（フォルダ名）

get-scripture

1つ以上のプロジェクトから、書、章、または節の範囲の聖句テキストを返します。

• projects — テキストを取得する1つ以上のプロジェクトID

• book — 3文字のUSFMブックコード（例：GEN、MAT、1CO）

• startChapter / startVerse / endChapter / endVerse — オプション。書全体の場合は4つすべてを省略し、章全体の場合は節を省略し、範囲全体（章をまたいでも可）を指定します。

• allowPartial — trueの場合、エラーを返す代わりに、欠落しているプロジェクト/書/節を黙って省略します。

出力はプレーンな聖句テキストのみです（セクション見出し、書名、脚注、相互参照はありません）。1行に1節で、BOOK CHAPTER:VERSE textの形式で出力されます。

複数のプロジェクトが要求された場合、各行の先頭にプロジェクトIDが付加され、節はプロジェクトごとにインターリーブされます。

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

ソーステキスト内の節の範囲指定（例：\v 6-7）は、節番号ごとに複製されるのではなく、6-7というラベルの付いた1行として返されます。

開発

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

テストは、myParatextProjects/フォルダからParatextプロジェクトデータを読み取ります。

謝辞

このプロジェクトが依存しているUSFMパーサーであるusfm-jsを提供してくれたunfoldingWordに感謝します。

今後の予定

• 自動インストールを提供する（例：'npx @milesnl/ptx-mcp --install'）

• Gemini CLIなどで試す