LeomaiaJr/wol-mcp-server

WOL MCP Server

An MCP server that gives LLMs read-only access to the Watchtower Online Library (WOL).

Features

• Advanced search with operators
• Document retrieval (always Markdown)
• Browse publication types
• Multilingual support (dynamic WOL language config)
• Robust error handling and retry logic

Installation

# Clone and install dependencies
git clone https://github.com/LeomaiaJr/wol-mcp-server.git
cd wol-mcp
npm install

# Build the server
npm run build

Available Tools

wol_search

Search the Watchtower Online Library with operators and pagination.

Parameters:

• query (string, required)
• useOperators (boolean, default: true)
• scope ("sen" | "par" | "art", default: "par")
• publications (array; see list below)
• language (string, default: "en")
• sort ("occ" | "newest" | "oldest", default: "occ")
• page (integer, default: 1)
• limit (integer, 1-100, default: 10) — applies only to document results

Search operators:

• & or + (AND), | or / (OR), ! (NOT), && or ++ (adjacent), "..." (phrase), * (wildcard), ? (single char), (...) (group)

wol_get_document

Retrieve full content of a specific document (always Markdown).

Parameters:

• url (string, required) — full WOL document URL

Output includes: title, publication, URL, optional date/volume/issue, subheadings, similar materials, followed by the article content. Bible citation links (/wol/bc) are inlined as plain text.

wol_browse_publications

Browse available publications by type.

Parameters:

• type (string) — optional filter
• language (string, default: "en")
• year (integer) — optional year filter

Publication types (common): w, g, bk, bi, it, dx, yb, syr, sgbk, mwb, km, brch, bklt, es, trct, kn, pgm, ca-copgm, ca-brpgm, co-pgm, manual, gloss, web

Available Resources

wol://publications

Lists all available publication types with descriptions.

wol://operators

Details on search operators and examples.

wol://languages

Supported languages for multilingual access.

Development (Cloudflare Workers)

# Install dependencies
npm install

# Run locally (wrangler dev)
npm start
# Local MCP endpoint: http://localhost:8787/sse

# Optional: open MCP Inspector in another terminal and connect to the local endpoint
npx @modelcontextprotocol/inspector@latest

# Type check
npm run type-check

# Deploy to Cloudflare
npx wrangler deploy

Deploy to Cloudflare Workers (Remote MCP)

Cloudflare Workers let you run a remote MCP server reachable over HTTP/SSE. This repo’s server currently starts via stdio (subprocess) using StdioServerTransport. To expose it remotely, deploy a Workers-based MCP server that implements the HTTP/SSE transport and wires the same tools. Below are two practical paths.

Option A — Quick deploy (authless template)

1. Create a new Workers project from Cloudflare’s authless remote MCP template:

npm create cloudflare@latest -- wol-mcp-worker --template=cloudflare/ai/demos/remote-mcp-authless
cd wol-mcp-worker

2. Develop locally:

npm start
# Server runs at http://localhost:8787/sse

3. Deploy (Wrangler is already authenticated on your machine):

npx wrangler@latest deploy

4. Connect using the MCP Inspector:

npx @modelcontextprotocol/inspector@latest
open http://localhost:5173
# Enter your server URL, e.g. http://localhost:8787/sse or https://<worker>.<account>.workers.dev/sse

5. Use with a local proxy:

{
  "mcpServers": {
    "wol-remote": {
      "command": "npx",
      "args": ["mcp-remote", "https://<worker>.<account>.workers.dev/sse"]
    }
  }
}

Option B — Add authentication (OAuth)

Start from Cloudflare’s GitHub OAuth example and deploy:

npm create cloudflare@latest -- wol-mcp-github-auth --template=cloudflare/ai/demos/remote-mcp-github-oauth
cd wol-mcp-github-auth
npx wrangler@latest deploy

Follow the guide to register OAuth apps and set secrets (GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET). See: Cloudflare “Build a Remote MCP server” guide.

Porting this server’s tools

• This repo is stdio-only. Workers cannot run stdio subprocesses, so you do not deploy dist/index.js directly.
• Reuse logic by moving the WOL tool handlers (e.g., WOLService) into the Workers project and registering equivalent tools there.
• Cloudflare Workers support the MCP HTTP/SSE transport out of the box in their templates. Implement tools that call the same methods you see in this repo’s wol_search, wol_get_document, and wol_browse_publications handlers.

Notes:

• Spec reference: MCP transports (stdio and Streamable HTTP). Workers templates expose an /sse endpoint compatible with MCP clients.
• For clients that don’t yet support remote MCP natively, use mcp-remote as shown above.

Configuration

Environment Variables

• NODE_ENV - Environment (development/production)
• LOG_LEVEL - Logging level (error/warn/info/debug)

Service Availability

Currently, no server-side rate limiting is enforced. Upstream availability from WOL may occasionally result in temporary outages (e.g., 502/503), which are surfaced as SERVICE_UNAVAILABLE errors.

Examples

Basic Search

Query: "Jesus Christ"
Result: Exact phrase search across all publications

Advanced Search with Operators

Query: (Jesus | Christ) & Jehovah & !Trinity
Result: Documents containing (Jesus OR Christ) AND Jehovah but NOT Trinity

Publication-Specific Search

Query: prayer
Publications: ["w", "g"]  // Watchtower and Awake! only
Result: Prayer-related articles from these magazines

Multilingual Search

Query: "reino de Dios"
Language: "es"
Result: Spanish content about God's Kingdom

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-feature
3. Make changes and add tests
4. Commit: git commit -am 'Add new feature'
5. Push: git push origin feature/new-feature
6. Submit a Pull Request

License

MIT License - see LICENSE file for details.

Disclaimer

This is an unofficial MCP server for accessing the Watchtower Online Library. It is not affiliated with or endorsed by Jehovah's Witnesses or the Watchtower Bible and Tract Society.