README.md
Fast, structured Scripture access, semantic exploration, and theological analysis
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 referen |
Tools (8)
explore_scripturePrimary entry point for open-ended queries, using semantic topic indexing and keyword search.get_passage_with_contextRetrieves a verse along with its surrounding neighbors for interpretation and analysis.get_passageExact text retrieval for multi-verse passages or ranges.get_cross_referencesFinds thematically related verses for a given verse, ranked by connection strength.compare_passagesCompares two Bible passages to reveal shared and unique verses.search_scripturePerforms an exact keyword or phrase match search.get_verse_of_the_dayReturns today's curated Verse of the Day.resolve_referenceValidates and canonicalizes a Bible reference into structured identifiers.Environment Variables
BIBLEBRIDGE_API_KEYAPI key for accessing the BibleBridge service; optional for demo usage.Configuration
claude_desktop_config.json
{"mcpServers": {"biblebridge": {"command": "node", "args": ["/absolute/path/to/biblebridge-mcp/server.js"], "env": {"BIBLEBRIDGE_API_KEY": "your_key_here"}}}}Try it
→What does the Bible say about the concept of grace?
→Explain Romans 8:1-4 in its immediate context.
→Compare the creation accounts in Genesis 1 and Genesis 2.
→Find verses related to the theme of forgiveness in the book of Matthew.
→What is today's verse of the day?