JW Research MCP

A remote Model Context Protocol server for traceable research across JW.org and the Watchtower Online Library. This project extends advenimus/jw-mcp with full WOL articles, publication pagination, direct library search, Study Bible footnotes, full-text cross-references, daily texts, caching, and optional server-side research synthesis with Kimi. Paragraphs, scriptures, related articles, and publication images retain direct source links for verification.

What is preserved

The original tool names and workflows remain available:

• search_bible_books

• get_bible_verse

• get_verse_with_study

• get_bible_verse_url

• getWorkbookLinks / getWorkbookContent

• getWatchtowerLinks / getWatchtowerContent

• get_jw_captions

get_verse_with_study.fields now also accepts footnotes. WOL exposes translation footnotes separately from both study notes and marginal cross-references, so no content is duplicated between those fields.

Related MCP server: JW MCP Server

Research tools

All network-backed responses contain:

{
  "metadata": {
    "source_url": "https://...",
    "timestamp": "2026-07-28T00:00:00.000Z",
    "cache_hit": false
  }
}

The default cache TTL is 15 minutes. Retrieval tools accept langwritten; supported WOL routes currently include E, S, F, X, I, T, J, KO, and U. Research retrieval tools support format: "json" and format: "markdown".

Markdown output uses clickable titles, paragraph source anchors, scripture references, footnotes, related articles, and image links. JSON output retains both plain text and source URLs for programmatic use.

Deep and conversational research

analyze_research supports four modes:

• answer — direct evidence-based response

• explore — map themes and connections

• compare — contrast publications, passages, or time periods

• verify — audit a claim and identify missing evidence

Use depth: "focused", "deep", or "exhaustive". For follow-up questions, pass a concise conversation_context; it preserves continuity but is never treated as source evidence. Every result includes a short answer, deep synthesis, source-linked key points, confidence ratings, consistency or tension findings, uncertainties, a source index, and suggested follow-ups.

For maximum accuracy, retrieve broad evidence in bounded pages first, include each block's source and source_url, and then call analyze_research.

Publication pagination

get_book_content treats chapter as a 1-based sequential entry in the publication TOC. A call returns at most three chapters and 25 paragraphs per chapter. Use page and next_page, or an explicit paragraph_range, to walk the content without placing an entire bound volume in one model context.

{
  "publication_code": "it",
  "chapter_range": "1-3",
  "page": 1,
  "page_size": 15,
  "langwritten": "E",
  "format": "json"
}

For large reference works such as Insight on the Scriptures, get_publication_toc also exposes WOL's natural TOC pages.

Local development

Requires Node.js 20 or newer.

npm install
npm run typecheck
npm test
npm start

To test Streamable HTTP:

cp .env.example .env
npm run build
MCP_TRANSPORT=http MCP_AUTH=false npm run start:http

Then run the MCP Inspector:

npx @modelcontextprotocol/inspector

Connect it to http://localhost:8080/mcp.

The live WOL smoke test is:

npm run build
node scripts/smoke-live.mjs

Environment variables

Railway

The included multi-stage Dockerfile compiles TypeScript and the included railway.toml uses /health for deployment health checks. Configure the environment variables above, deploy, generate a Railway domain, then set MCP_BASE_URL to that exact https://... domain and redeploy.

The MCP endpoint is:

https://YOUR-RAILWAY-DOMAIN/mcp

Keep this connector separate from existing services until its retrieval and analysis behavior has been verified with your own research workflow.

Tests

The automated suite verifies:

• footnotes remain distinct from study notes and cross-references

• full-article paragraph numbering and marker preservation

• linked paragraph citations, media captions, and related-material parsing

• hard paragraph pagination bounds

• cache-hit behavior

• localized WOL route construction

• schema-validated analyze_research JSON without Markdown fences

The live smoke test additionally verifies a real Insight TOC and pagination, WOL search, article media, related research trails, full-text cross-references, daily text parsing, and cached repeats.

Attribution and license

Forked from advenimus/jw-mcp. Licensed under the MIT license of the upstream project.