ptx-mcp

MCP（模型上下文协议）服务器，直接从本地 Paratext 项目文件夹（USFM 文件）读取经文文本，并将其作为工具提供给 LLM 调用。

支持的提示词示例

安装服务器后（见下文），你可以用自然语言向 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 必须在本地机器上运行，而不是在云端。

  • 我认为这意味着你在开始聊天时必须选择"聊天"选项，而不是"协作"选项。 "协作"选项似乎（至少有时？）在无法访问本地机器的云沙箱中运行。

环境要求

• Node.js 18+

  • 我认为安装 Claude Desktop 时会自动安装

• 磁盘上有一个或多个 Paratext 项目文件夹（每个文件夹包含 Settings.xml 和 USFM 书卷文件）

设置/安装

在 Claude Desktop 中

• 点击左下角带有你名字的按钮

• 点击"设置"

• 点击"开发者"

• 点击"编辑配置"

• 双击 'claude_desktop_config.json' 打开编辑器

编辑 'claude_desktop_config.json'，按如下方式添加服务器

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

重要！关闭并重新启动 Claude 以加载新的 MCP 服务器。

当你第一次向 Claude 发出与 Paratext 相关的命令时，ptx-mcp 包将自动从 NPM 库下载。

要测试安装，请向 Claude 提问："列出 Paratext 项目"

安装故障排除

• 转到命令行并尝试 'npx -y @milesnl/ptx-mcp'

  • 成功的结果是运行后等待终端输入。按 Control C 终止。 如果它打印错误消息，则说明我们因某种原因无法访问 @milesn/ptx-mcp NPM 包。

• 重新启动 Claude 后，转到"设置/开发者"。 这应该会显示 ptx-mcp 作为本地 MCP 服务器。 如果没有，则说明加载出了问题。

• 如果显示"ptx-mcp 失败"，请点击"查看日志"以了解原因。

安装说明

如果你的"我的 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

返回一个或多个项目中某书卷、某章或某段经文范围的经文文本。

• projects — 要获取文本的一个或多个项目 ID

• book — 3 字母 USFM 书卷代码（例如 GEN、MAT、1CO）

• startChapter / startVerse / endChapter / endVerse — 可选；省略全部四个参数则获取整卷书，省略经文参数则获取整章，或指定完整范围（可以跨章）

• allowPartial — 如果为 true，则静默省略缺失的项目/书卷/经文，而不是返回错误

输出仅为纯经文文本——没有章节标题、书名、脚注或交叉引用——每行一节经文，格式为 书卷 章:节 文本。

当请求多个项目时，每行以项目 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 的单行返回，而不是按每个经文编号重复。

开发

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

测试从 myParatextProjects/ 文件夹读取 Paratext 项目数据。

致谢

特别感谢 unfoldingWord 提供 usfm-js，这是本项目依赖的 USFM 解析器。

待办事项

• 提供自动安装，例如 'npx @milesnl/ptx-mcp --install'

• 尝试与 Gemini CLI 等配合使用。