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

Via npm (recommended):

npx -y biblebridge-mcp-server

Via git clone:

git clone https://github.com/ZeroCoolZiemer/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

Option 1 — npm (recommended)

npx -y biblebridge-mcp-server

No install step needed. Always runs the latest version.

Configuration (optional)

Set your API key as an environment variable — or omit it to use the built-in demo key:

BIBLEBRIDGE_API_KEY=your_key_here npx -y biblebridge-mcp-server

Option 2 — Clone and Install

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

Configuration (optional)

Create a .env file in the repo root:

BIBLEBRIDGE_API_KEY=your_key_here

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

Execution

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

Via npm (recommended):

{
  "mcpServers": {
    "biblebridge": {
      "command": "npx",
      "args": ["-y", "biblebridge-mcp-server"],
      "env": {
        "BIBLEBRIDGE_API_KEY": "your_key_here"
      }
    }
  }
}

Via git clone:

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

Claude Code

Via npm:

claude mcp add biblebridge -- npx -y biblebridge-mcp-server

Via git clone:

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.