biblebridge-mcp

Lightweight, production-ready MCP server for fast, structured Scripture access, semantic exploration, contextual retrieval, and theological analysis via the BibleBridge API.

---

Requirements

• Node.js: 18+
• BibleBridge API Key: Free tier included — upgrade at holybible.dev for higher limits

---

Quick Start

git clone https://github.com/your-username/biblebridge-mcp.git
cd biblebridge-mcp
npm install
node server.js

Runs instantly with a built-in demo key (bb_free_demo) — no setup required. Each installation gets its own quota via a unique client ID, so you won't share limits with other users. For production use, get a free personal API key at holybible.dev/signup.

---

Installation & Setup

1. Clone and Install

git clone https://github.com/your-username/biblebridge-mcp.git
cd biblebridge-mcp
npm install

2. Configuration

The server works out of the box with the demo key. To use your own API key (recommended for any real usage):

Copy .env.example to .env:

BIBLEBRIDGE_API_KEY=your_key_here

Get a free key at holybible.dev/signup — 500 requests/day, no credit card required.

3. Execution

Run the server:

node server.js

Debug with MCP Inspector:

npx @modelcontextprotocol/inspector node server.js
# Opens MCP Inspector for interactive tool testing

---

Client Configuration

Claude Desktop

Add the following to your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "biblebridge": {
      "command": "node",
      "args": ["/absolute/path/to/biblebridge-mcp/server.js"],
      "env": {
        "BIBLEBRIDGE_API_KEY": "your_key_here"
      }
    }
  }
}

Claude Code

claude mcp add biblebridge -- node /absolute/path/to/biblebridge-mcp/server.js

After adding, restart Claude Code to load the MCP server.

---

Tools

Tool	Endpoint(s)	Description
explore_scripture	/topics + /search + /passage	Primary entry point for most Bible questions, especially open-ended queries like "What does the Bible say about X?" Tries the topic index first (semantic), falls back to keyword search if needed, and returns relevant passages with full text. Use this by default unless the query clearly calls for a more specific tool.
get_passage_with_context	/passage + /context + /passage	Default choice for single-verse queries. Retrieves a verse along with its surrounding neighbors so the full thought and narrative are preserved. Use this for interpreting, explaining, or analyzing a verse. Best suited for single-verse inputs.
get_passage	/passage	Exact text retrieval for multi-verse passages or ranges (e.g. "Romans 8:1-4, 28; 12:1-2"). Do not use for single-verse interpretation — use get_passage_with_context instead.
get_cross_references	/cross-references	Thematically related verses for a given verse, ranked by connection strength (very_high → low). Use to discover related passages or follow a theme from a specific verse.
compare_passages	/diff + /passage	Compare two Bible passages to reveal shared and unique verses. Shows overlap, what is unique to each, and full verse text for all sections. Use to analyze overlap, contrast themes, or study differences between passages.
search_scripture	/search	Exact keyword or phrase match (e.g. "faith without works"). Use only when searching for a specific phrase or wording — otherwise prefer explore_scripture for thematic or general questions.
get_verse_of_the_day	/votd	Returns today's curated Verse of the Day (KJV) — rotates daily.
resolve_reference	/resolve	Validates and canonicalizes a Bible reference. Returns structured identifiers (book_id, chapter, verse, osis_id). Use only when you need to verify or normalize a reference before further processing.

---

---

Tool Selection Guide

Which tool to use?

Use Case	Tool
General or topic-based questions	explore_scripture ← default
Single verse — interpreting or explaining	get_passage_with_context
Multi-verse passage or range	get_passage
Exact phrase search	search_scripture
Compare two passages	compare_passages
Related verses from a specific verse	get_cross_references
Today's verse of the day	get_verse_of_the_day
Validate or normalize a reference	resolve_reference

Tool Hierarchy

The tools form three natural layers:

High-level (LLM-friendly defaults)

• explore_scripture — semantic orchestrator, the default entry point
• get_passage_with_context — default for single-verse work
• compare_passages — structured passage analysis

Mid-level (direct retrieval)

• get_passage — exact multi-verse retrieval
• get_cross_references — thematic traversal
• search_scripture — verbatim phrase matching
• get_verse_of_the_day — daily curated verse

Specialized

• resolve_reference — reference validation and normalization; most tools handle resolution internally, so reach for this only when you specifically need the canonical output

---

resolve_reference — Handling Messy Input

When you do need to validate or normalize a reference, resolve_reference is the most capable tool available. It handles typos, abbreviations, encoding artifacts, and informal phrasing, returning a stable canonical form.

What it resolves

Raw Input	What's Wrong	Resolved
"Mathew 5:3"	Common misspelling	Matthew 5:3
"john316"	No spaces or punctuation	John 3:16
"Apoc 22:1"	Alternate tradition name (Apocalypse)	Revelation 22:1
"Phil.4:6–7,9"	En-dash + no spaces + non-contiguous verses	Philippians 4:6-7,9
"Ps.23, vv.1—3"	vv. notation + em-dash from Word	Psalms 23:1-3
"kjv iitim3:16-17"	Malformed ordinal + no space + translation prefix	2 Timothy 3:16-17 (KJV)

Real example — "kjv iitim3:16-17"

{
  "type": "single",
  "valid": true,
  "input": "2 tim 3:16-17",
  "book": {
    "key": "2TI",
    "book_id": 55,
    "osis": "2Tim",
    "name": "2 Timothy",
    "slug": "2-timothy"
  },
  "spans": [
    {
      "start": { "chapter": 3, "verse": 16 },
      "end": { "chapter": 3, "verse": 17 }
    }
  ],
  "osis_id": "2Tim.3.16-2Tim.3.17",
  "translation": "KJV",
  "parse_quality": 0.92,
  "confidence_class": "corrected",
  "confidence_explanation": [
    {
      "type": "book_alias",
      "impact": -0.08
    }
  ],
  "normalization_steps": [
    "translation_extracted"
  ]
}

Key fields:

• confidence_class — indicates whether corrections were applied (exact, corrected, etc.)
• parse_quality — numeric score usable in agent logic to decide whether to confirm with the user
• confidence_explanation — exactly what caused any confidence deduction
• osis_id — stable canonical identifier for downstream storage and interop

Ambiguity detection

When a reference is genuinely ambiguous, the resolver returns ambiguous: true with ranked candidates instead of guessing silently.

Input: "Samuel 3:1"

{
  "type": "single",
  "valid": false,
  "ambiguous": true,
  "candidates": [
    { "key": "1SA", "id": 9, "name": "1 Samuel", "osis": "1Sam", "weight": 70, "score": 0.8275 },
    { "key": "2SA", "id": 10, "name": "2 Samuel", "osis": "2Sam", "weight": 70, "score": 0.8275 }
  ]
}

An AI agent receiving this can prompt the user naturally:

"Did you mean 1 Samuel 3:1 or 2 Samuel 3:1?"

The ambiguous flag makes the distinction machine-readable so your application can handle it gracefully rather than passing a bad reference downstream.

---

Example Prompts

• "What does the Bible say about forgiveness?"
• "Read Romans 8:1–10 in the WEB translation."
• "Show me John 3:16 with surrounding context."
• "Compare Romans 8 and Galatians 5."
• "Find verses about covenant."
• "What are the cross-references for Hebrews 11:1?"
• "What's today's verse of the day?"

---

Response Format

Tools return structured, readable text optimized for direct use in AI responses, while preserving canonical data from the underlying API.

• Deterministic canonical references
• Translation-aware responses
• Structured grouping for comparisons and cross-references
• JSON output for validation and grounding (resolve_reference)

---

Design Philosophy

BibleBridge MCP is designed around AI workflows, not raw API endpoints. Instead of exposing low-level primitives, it provides composed tools for:

• Grounded Scripture retrieval
• Semantic exploration of topics
• Context-aware interpretation
• Cross-reference traversal
• Passage comparison and reasoning

All tools accept natural Scripture references (e.g. "John 3:16", "rom 8:1–4, 28") and handle normalization internally — you do not need to call resolve_reference before using other tools.

All tools are built on a deterministic canonical coordinate system to ensure accuracy and prevent hallucination. Internally, all operations are batched and normalized to canonical verse identifiers for efficiency and consistency.

---

Why BibleBridge MCP?

• Unified Interface: A single point of access for search, context, and cross-references
• Agent-Optimized: Designed for structured, predictable AI consumption
• Plug-and-Play: Works out of the box with zero initial setup
• Built for Study: Supports deeper workflows beyond simple verse lookup
• Canonical Reference Engine: Handles messy, ambiguous, and real-world Scripture inputs with deterministic normalization

---

Technical Details

Property	Details
API Provider	https://holybible.dev/
Supported Translations	KJV, ASV, WEB, YLT, LSG, RVR, LUT, CUV, ARA, KRV
Rate Limiting	Managed per user via client identifiers (IP + API key)
License	MIT

---

Built for AI agents, Bible apps, and advanced Scripture study workflows.