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 Selection Guide

Which tool to use?

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

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

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