biblebridge-mcp
README.md
# 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](https://holybible.dev/signup) for higher limits
---
## Quick Start
```bash
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](https://holybible.dev/signup).
---
## Installation & Setup
### 1. Clone and Install
```bash
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`:
```env
BIBLEBRIDGE_API_KEY=your_key_here
```
Get a free key at [holybible.dev/signup](https://holybible.dev/signup) — 500 requests/day, no credit card required.
### 3. Execution
Run the server:
```bash
node server.js
```
Debug with MCP Inspector:
```bash
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`
```json
{
"mcpServers": {
"biblebridge": {
"command": "node",
"args": ["/absolute/path/to/biblebridge-mcp/server.js"],
"env": {
"BIBLEBRIDGE_API_KEY": "your_key_here"
}
}
}
}
```
### Claude Code
```bash
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"`
```json
{
"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"`
```json
{
"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.*