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 · API catalog · llms.txt · User documentation