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.

Research tools

Tool	Purpose
get_footnotes	Full translation footnotes for a verse
get_article_full	Complete article with paragraph anchors, live inline links, images, and related material
get_article_media	Paginated full-size images, thumbnails, captions, alt text, and exact source anchors
get_related_content	Linked subheadings and WOL-recommended similar material
get_book_content	Bounded publication slices by sequential TOC entry and paragraph page
get_publication_toc	Direct article URLs, including natural TOC pages for large works
search_wol_library	Direct WOL full-text search
search_wol_media	Topic search for images across matching WOL articles
get_cross_references	Marginal references with complete cited verse text
get_daily_text	Daily scripture and comment for a date
analyze_research	Conversational Kimi K3 synthesis with evidence, URLs, confidence, gaps, and follow-ups

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

Variable	Default	Description
MCP_TRANSPORT	stdio	Use http for Railway
PORT / MCP_PORT	8080	HTTP listen port
MCP_BASE_URL	local URL	Public Railway URL used in OAuth metadata
MCP_AUTH	true	Set false only for isolated testing
MCP_AUTH_SECRET	—	Required when OAuth is enabled; minimum 8 characters
KIMI_API_KEY	—	Required only by analyze_research
KIMI_MODEL	kimi-k3	Kimi model used for research synthesis
KIMI_BASE_URL	https://api.moonshot.ai/v1	OpenAI-compatible Kimi API base URL
CACHE_TTL_SECONDS	900	In-memory fetch cache TTL
DEFAULT_LANGUAGE	E	Default langwritten value

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.