# BibleBoard API & MCP server

Read, search and cross-reference the Bible from your app or AI agent — and, with a user’s permission, work with their studies.

## Overview

BibleBoard exposes the Bible text behind its reader as a small, keyless JSON API, and a user’s own studies and mindmaps through an MCP server. Both run on the same service, so a passage fetched over REST and one fetched by an AI assistant are identical.

### What is public

Passages, full-text search and cross-references in five versions — no account, no key. Anything that belongs to a user (studies, mindmaps) needs that user’s permission: sign in through OAuth from an MCP client, or send a BibleBoard API key.

**REST API**
https://bibleboard.org/api/v1 — JSON over HTTPS, GET only, CORS open to every origin.

**OpenAPI 3.1**
https://bibleboard.org/openapi.json — generate a client or import it into your agent framework.

**API catalog**
https://bibleboard.org/.well-known/api-catalog (RFC 9727) links the description, these docs and the status endpoint.

**MCP server**
https://bibleboard.org/mcp — the same Bible tools plus signed-in tools for a user’s studies. See “MCP server” below.

## REST endpoints

Every endpoint is a GET that returns JSON. References are forgiving: abbreviations (“jn 3:16”), ranges within a chapter (“1 Cor 13:4-7”), whole chapters (“Psalm 23”) and Spanish book names (“Salmos 23”) all work.

### GET /translations

The versions the API serves, with language, whether search covers them, and any attribution you must show.

curl https://bibleboard.org/api/v1/translations ### GET /passages A verse, a range within one chapter, or a whole chapter — verse by verse (with section headings) and as plain prose, plus a citation and a link into the BibleBoard reader.

**reference**
Required. e.g. John 3:16-18

**translation**
BSB (default), KJV, NET, HEB or RVR. Case-insensitive.

curl "https://bibleboard.org/api/v1/passages?reference=John+3:16-18&translation=BSB"{ "reference": "John 3:16-18", "citation": "John 3:16-18 (BSB)", "translation": { "id": "BSB", "fullName": "Berean Standard Bible", "license": "public-domain", … }, "verses": [ { "chapter": 3, "verse": 16, "text": "For God so loved the world that He gave His one and only Son, …", "heading": "For God So Loved the World" }, … ], "text": "For God so loved the world …", "url": "https://bibleboard.org/read/john-3?v=BSB&verse=16" } ### GET /search Full-text search on the reader’s own engine: word stems (“loved” finds “love”), small typos, and "double-quoted phrases" as exact matches. Best matches first. Available for BSB, KJV, NET and RVR.

**q**
Required. Words or a quoted phrase, up to 200 characters.

**translation**
BSB (default), KJV, NET or RVR.

**limit**
1–100, default 20. total reports how many verses matched in all.

curl "https://bibleboard.org/api/v1/search?q=love+your+enemies&translation=KJV&limit=5" ### GET /cross-references Related verses for a verse or a short range, most-voted first, from OpenBible.info’s community-voted dataset. A range merges its verses’ references.

**reference**
Required. A verse or verse range, e.g. Romans 8:28.

**limit**
1–100, default 20.

curl "https://bibleboard.org/api/v1/cross-references?reference=Romans+8:28&limit=5" ### GET /health Service status as application/health+json. Never cached.

curl https://bibleboard.org/api/v1/health  ## MCP server Connect an AI assistant to BibleBoard over the Model Context Protocol at https://bibleboard.org/mcp. Bible tools work without an account; tools that read a user’s own studies ask that user to sign in and approve the app.

### Endpoint

Streamable HTTP at https://bibleboard.org/mcp: POST JSON-RPC 2.0, answered as application/json. The server is stateless (no session id, no server-sent stream; GET returns 405) and speaks protocol versions 2025-11-25, 2025-06-18 and 2025-03-26.

Its server card is at https://bibleboard.org/.well-known/mcp/server-card.json.

curl -s https://bibleboard.org/mcp \ -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"get_passage","arguments":{"reference":"Psalm 23","translation":"KJV"}}}' ### Add it to your assistant Use the URL above as a remote (HTTP) MCP server. Sign-in happens in the browser the first time a signed-in tool is used.

**Claude**
Settings → Connectors → Add custom connector, URL https://bibleboard.org/mcp.

**Claude Code**
claude mcp add --transport http bibleboard https://bibleboard.org/mcp

**ChatGPT**
With developer mode on, Settings → Apps & Connectors → Create, URL https://bibleboard.org/mcp, authentication OAuth.

**Cursor**
In .cursor/mcp.json: {"mcpServers":{"bibleboard":{"url":"https://bibleboard.org/mcp"}}}

**VS Code**
In .vscode/mcp.json: {"servers":{"bibleboard":{"type":"http","url":"https://bibleboard.org/mcp"}}}

### Tools

Every tool is read-only and returns structured JSON (also as text). A bad reference or unknown id comes back as a tool error the model can read and correct.

**list_translations**
Versions served (BSB, KJV, NET, HEB, RVR) with licensing and the NET copyright line.

**get_passage**
A verse, range or chapter: verses, joined text, citation and a reader link. Args: reference, translation.

**search_bible**
Verses matching words or a phrase, best first. Args: query, translation, limit.

**get_cross_references**
Related passages for a verse (OpenBible.info, CC BY), most-voted first. Args: reference, limit.

**list_studies (sign-in)**
The user’s studies (owned or shared), newest first, with links.

**get_study (sign-in)**
One study as Markdown — headings, notes and the passages in it. Args: id.

**list_mindmaps (sign-in)**
The user’s mindmaps (canvas boards), newest first, with links.

### Authentication

Public tools need nothing. Calling a sign-in tool without credentials returns HTTP 401 with a WWW-Authenticate header pointing at the protected-resource metadata, which MCP clients follow automatically.

BibleBoard is an OAuth 2.1 authorization server: dynamic client registration (no pre-registration), authorization code with PKCE (S256), refresh tokens with offline_access. The user signs in and approves the app on a consent screen. Access tokens last an hour; revoke one at any time.

A BibleBoard API key (bb_…) also works, as x-api-key or a Bearer token. Keys are issued on request; OAuth is the self-serve route.

**Authorization server metadata**
https://bibleboard.org/.well-known/oauth-authorization-server

**Protected resource metadata**
https://bibleboard.org/.well-known/oauth-protected-resource/mcp

**Agent guide**
https://bibleboard.org/auth.md — register, authorize, exchange, use, revoke, step by step.

## Errors, caching and limits

### Errors

Every error is JSON with a stable code, a message, a hint that says how to fix the call, and a link back here. 400 means the request needs changing, 404 that the version doesn’t contain the passage (the Hebrew is Old Testament only), 503 that the text couldn’t be loaded — retry.

{ "error": { "code": "invalid_reference", "message": "Could not read \"Jhn\" as a Bible reference.", "hint": "Use book chapter:verse, e.g. \"John 3:16\" …", "docs": "https://bibleboard.org/developers" } } ### Caching and fair use Responses carry Cache-Control (an hour, then served stale while refreshing) and are cached at Cloudflare’s edge. The text only changes when we re-publish a version, so cache freely on your side too.

### Rate limits

No key is needed; each client IP may make 120 requests per 60 seconds across the API and the MCP server. Every response states the policy in a RateLimit-Policy header (IETF RateLimit fields) and X-RateLimit-Limit. Over the limit you get 429 with a rate_limited error, Retry-After, and RateLimit showing zero remaining — wait that many seconds and retry.

## Versioning and deprecation

### Policy

The API is versioned in the path: /api/v1. Within v1 we only add — new endpoints, new optional parameters, new response fields — so ignore fields you don’t know.

A breaking change ships as /api/v2. The older version keeps working for at least 6 months after that; during that time its responses carry a Deprecation header (RFC 9745), a Sunset header with the shutdown date (RFC 8594), and a Link to this page with rel="deprecation". The change is also announced on bibleboard.org/updates.

The MCP server follows the same rule: tools and their inputs only grow; a tool is removed only after 6 months of being marked deprecated in its description.

## Translations and licensing

The API serves only versions we may redistribute. Other versions in the reader stay in the reader.

### Served

The /translations response carries each version’s license and attribution, so a client can show it without hard-coding this table.

**BSB**
Berean Standard Bible — public domain.

**KJV**
King James Version — public domain.

**NET**
NET Bible — quoted by permission of Biblical Studies Press. Whenever you show NET text, show its copyright line (in every response’s translation.copyright) and link it to https://netbible.org.

**HEB**
Hebrew Old Testament (Westminster Leningrad Codex) — public domain.

**RVR**
Reina-Valera 1909 — public domain.

### Not served

The ESV (its API terms don’t allow redistribution), the Greek New Testament (Nestle-Aland is copyrighted), and the Reina Valera Gómez and Biblia Libre. Asking for them returns 400 translation_not_available.

Cross-references come from OpenBible.info under CC BY; credit them when you display the list (each response includes an attribution string).

Machine-readable: [OpenAPI 3.1](https://bibleboard.org/openapi.json) · [API catalog](https://bibleboard.org/.well-known/api-catalog) · [llms.txt](https://bibleboard.org/llms.txt) · [User documentation](https://bibleboard.org/docs)

---

Source: https://bibleboard.org/developers