GetBible for AI applications

Connect an AI application to https://mcp.getbible.net/ using Streamable HTTP. Public access is free and requires no account or token. A single connection gives the application structured tools for scripture, reference lookup, full-text search, dictionaries, commentaries and public Bible topics.

GetBible MCP is a read-only bridge to the GetBible APIs. It retrieves published source material and keeps its provenance, native data and content rights. The same open-source Python package can run locally over stdio or be embedded in your own server. Source repository · Python package · Public support.

Connection details#

Setting	Value
Connection name	GetBible
Remote URL	https://mcp.getbible.net/
Transport	Streamable HTTP
Public authentication	No authentication
Default Bible, query and search version	v3
Other Bible, query and search version	Select api_version: "v2" explicitly
Dictionaries, commentaries and bookmarks	v1
Local command	getbible-mcp --transport stdio
Python requirement	Python 3.11 or later
Software license	GPL-2.0-or-later; content licenses remain separate

Use the remote URL exactly. The official service places the MCP protocol at the domain root, so adding /mcp, /v2 or /v3 creates a different URL. Upstream API versions belong in tool arguments. An MCP URL accepts protocol requests; it is not a REST path for a Bible reference. Connection reference.

Connect in ChatGPT developer mode#

1. Open ChatGPT Settings → Security and login and enable Developer mode.
2. Open Plugins, select the plus button, and create an MCP connection named GetBible. A useful description is “Read and search Bible translations, dictionaries, commentaries and public topics.”
3. Enter https://mcp.getbible.net/, select the public HTTP connection method, and choose No Authentication.
4. Create the connection and inspect the discovered tools.
5. Start a new conversation, open the tools or plus menu, and enable your GetBible connection.
6. Try: “Use GetBible to retrieve John 3:16–19 in the King James Version. Cite the returned source.”

Developer mode availability depends on your account and workspace policy. After the server adds or changes tools, refresh the development connection and start a new conversation. These steps create a development connection; the repository's prepared plugin package does not establish approval in a public plugin directory. Official OpenAI connection guide · Developer mode documentation.

The public ChatGPT connection uses no authentication. A GetBible administrator-issued bearer token is not an OAuth sign-in or a ChatGPT API-key login. Use optional tokens only in clients whose secure authentication settings support the header specified by the administrators. Access and tokens.

Useful things to ask#

• “Use GetBible to find the available Afrikaans translations, then show me Psalm 23 in the translation I choose.”
• “Find verses containing faith and hope in Romans and First Corinthians, with references and links to their sources.”
• “Retrieve John 1:1 using API v3. If its actual token data contains Strong's identifiers, look those up in a compatible dictionary and preserve the source attribution.”
• “Show me which commentary modules cover John 3. Read the selected module's comments that include verse 16, including comments spanning several verses.”
• “Find public topics connected to John 3 and retrieve the associated verses in KJV.”
• “Help me design an application using GetBible, including translation rights, version selection and the cache refresh policy.”

Specify the translation, source module and API version when they matter. A model should report an unavailable reference or missing commentary coverage instead of silently substituting another passage. Commentary is its author's interpretation; dictionary definitions and Bible quotations should remain distinguishable from the AI's explanation.

What the connection covers#

Service argument	Versions	Content	Website guide
api	v2, v3	Translation catalogs, books, chapters, complete scopes, indexes and checksums	Bible API
query	v2, v3	Individual, ranged and grouped Bible references	Query API
search	v2, v3	Full-text and reference search, filters, ranking, pagination and read-only POST	Search API
dictionaries	v1	Module discovery, indexes, entries, lexical links, provenance and checksums	Dictionaries
commentaries	v1	Module discovery, coverage, introductions, comments and checksums	Commentaries
bookmarks	v1	Public topics, verse coordinates, localized names and checksums	Bookmarks

There are nine versioned OpenAPI contracts behind these six service names. The generic tools expose the complete packaged contracts, while convenience tools simplify common tasks. The data is not flattened to a lowest common denominator: v3 tokens, spans, paragraphs and additional native fields remain available. Package releases and upstream API versions are independent.

Tools#

GetBible exposes the following 13 tools. Read the connection's discovered schemas before generating calls for exact parameter types, defaults and validation. Both Streamable HTTP and local stdio provide the same tool capabilities. Tool implementation.

Tool	Purpose and inputs
discover_apis	List contracts, source URLs and resource URIs. Optional service and api_version narrow discovery.
describe_api_operation	Require service and api_version; omit operation_id to list operations, or supply it for exact inputs and response schemas.
call_api_operation	Require service, api_version, operation_id; send named path/query inputs in parameters and a documented search POST object in body.
list_translations	Retrieve the selected version's catalog, including language and publisher metadata. api_version defaults to v3.
list_books	Discover numbers, localized names and hashes. Defaults to translation: "kjv" and api_version: "v3".
list_chapters	Discover chapter identifiers and hashes for a required translation and positive integer book.
get_scripture	Read a chapter, book or translation with before/after hash consistency checks. Provide book and chapter for a chapter; omit chapter for a book; omit both for a translation.
query_verses	Resolve references of 1–512 characters. Translation defaults to KJV; explicit versions prevent accidental mixing.
search_verses	Search 1–500 characters of text with typed filters, pagination and version selection.
search_dictionary_entries	Find entry identifiers in a freshly fetched dictionary index. Required dictionary and query; match is exact, prefix or contains; limit is 1–100, default 20; offset starts at 0.
get_hash	Read a scope's Bible SHA-1. kind is translation, book or chapter; provide the coordinates required by that scope.
get_hash_manifest	Read bulk hashes. kind is all_translations, translation or book; provide applicable translation/book inputs.
check_for_updates	Compare 1–100 saved scope records. Each item carries its own api_version, coordinates and actual current_hash; the result describes required invalidation.

All these tools are read-only and idempotent. Search POST submits a lookup; it does not publish content. MCP cannot edit a Bible, upload a translation or change a user's personal bookmarks. Generic operations accept declared contract routes, rather than arbitrary destination URLs.

Search filters#

Argument	Supported values or bounds
words	all (default), any, phrase
match	whole_word (default), substring
case_sensitive	Boolean, default false
diacritics	fold (default), exact, insensitive, sensitive
scope	bible (default), old_testament, new_testament, deuterocanon
book	Array of book numbers or names; at most 83 items
books	Comma-separated book selection
exclude	Array of excluded terms; at most 32 items
proximity	Integer 0–100; requires words: "all"
sort	canonical (default), relevance
limit	Integer 1–100, default 100
offset	Integer 0–10,000, default 0

A search recognized as a Bible reference may follow reference lookup behavior instead of ordinary full-text filters. Inspect the native response and its pagination. Do not assume that an empty or truncated page represents the entire dataset.

Copyable tool examples#

These objects describe a tool and its arguments for an MCP client or Inspector. They are not complete JSON-RPC requests. Your client discovers the protocol and supplies the appropriate request envelope.

Retrieve a passage#

{
  "tool": "query_verses",
  "arguments": {
    "translation": "kjv",
    "references": "John 3:16-19; 1 John 3:16-19,22",
    "api_version": "v3"
  }
}

Retrieve a chapter with its checksum#

{
  "tool": "get_scripture",
  "arguments": {
    "translation": "kjv",
    "book": 43,
    "chapter": 3,
    "api_version": "v3"
  }
}

Search within selected books#

{
  "tool": "search_verses",
  "arguments": {
    "search": "faith hope",
    "translation": "kjv",
    "api_version": "v3",
    "words": "any",
    "book": [45, 46],
    "sort": "relevance",
    "limit": 25,
    "offset": 0
  }
}

Preserve the native query, results and matches envelope. For full-text pages, inspect query.has_more and retain the same filters while increasing the offset by the chosen page size.

Inspect and call a complete API operation#

{
  "tool": "describe_api_operation",
  "arguments": {
    "service": "search",
    "api_version": "v3",
    "operation_id": "searchTranslationPost"
  }
}

{
  "tool": "call_api_operation",
  "arguments": {
    "service": "search",
    "api_version": "v3",
    "operation_id": "searchTranslationPost",
    "parameters": {"translation": "kjv"},
    "body": {"q": "faith hope", "words": "all", "proximity": 10, "limit": 25}
  }
}

Operation identifiers are scoped to a service and version. Preserve the returned input_name and JSON types. Repeated query values are arrays; a colliding path/query parameter uses the plain path name and query. prefix for the query input. For search POST, a query parameter overrides the body value and a path value overrides both. POST results use no-store. More source examples.

Dictionaries: discover, match, retrieve#

Start with call_api_operation using service: "dictionaries", api_version: "v1", operation_id: "listDictionaries". Choose an actual returned dictionaries[].id by source, language and purpose. Read getDictionaryMetadata with that ID before presenting definitions; retain the module's attribution, license, distribution notes and provenance.

For a discovered strongsgreek module and an actual Strong's token G3056, these calls locate and retrieve the entry:

{
  "tool": "search_dictionary_entries",
  "arguments": {
    "dictionary": "strongsgreek",
    "query": "G3056",
    "match": "exact",
    "limit": 20,
    "offset": 0
  }
}

{
  "tool": "call_api_operation",
  "arguments": {
    "service": "dictionaries",
    "api_version": "v1",
    "operation_id": "getDictionaryEntry",
    "parameters": {"dictionary": "strongsgreek", "entry": "G3056"}
  }
}

Pass the exact identifier returned by the index. An entry filename cannot safely be guessed from a headword; several definitions can share a key and use occurrence suffixes such as --2. The search helper matches headwords, IDs and aliases, not the full text of definitions. Text matching ignores case and combining accents, while identifier matching preserves exact case. Follow next_offset with unchanged inputs until no further relevant results remain.

For integrations that need a complete dictionary index, getDictionaryIndex through call_api_operation returns the selected module's full index. Account for its size when processing it in your application. Prefer search_dictionary_entries for individual word lookups, and do not claim no match after seeing only a truncated index. There is no static dictionary ?q= route, and search_verses searches scripture rather than dictionary definitions.

Preserve native Strong's tokens, including Hebrew H0 prefixes such as H0430. An English word alone does not establish its original-language lemma. Use the passage's actual token data, retain ambiguous identifiers, and never invent annotations missing from the source.

Optional see_also and backlinks fields describe directed links within a module. Fetch relevant linked entries by their supplied IDs, retain link direction, and stop cycles with a visited set. These links are not automatically proof of synonymy or etymology. Scripture references are separate: resolve their canonical ref through query_verses in the selected Bible version and translation. Study workflow source.

Commentaries: check coverage first#

Use listCommentaries, choose a returned module ID, and read getCommentaryMetadata. Then call getCommentaryBooks to discover the actual book and chapter coverage. Do not assume every module covers all Bible books or continuous chapters.

If the discovered mhc module includes book 43, chapter 3:

{
  "tool": "call_api_operation",
  "arguments": {
    "service": "commentaries",
    "api_version": "v1",
    "operation_id": "getCommentaryChapter",
    "parameters": {"commentary": "mhc", "book": 43, "chapter": 3}
  }
}

To select comments on verse 16, include every entry whose verses array contains 16; if that array is absent, compare verse. A range anchored at verse 14 may cover verse 16. Preserve multiple matching comments and their original text, ranges, osis and references.

A discovered chapter 0 is a book introduction. Verse 0 within a chapter is introductory content. Keep both as context without renumbering them. Cross-chapter comments may occur in each affected chapter; avoid repeating the same quotation while retaining the full coverage. Fetch Bible text separately with query_verses and cite the commentary module and the returned source.url.

Public topics and bookmarks#

{
  "tool": "call_api_operation",
  "arguments": {
    "service": "bookmarks",
    "api_version": "v1",
    "operation_id": "getTopics"
  }
}

{
  "tool": "call_api_operation",
  "arguments": {
    "service": "bookmarks",
    "api_version": "v1",
    "operation_id": "getChapter",
    "parameters": {"book": 43, "chapter": 3}
  }
}

The bookmark dataset supplies topics and verse coordinates, not scripture text. Resolve selected coordinates through the Bible or query API in the reader's chosen translation. These are public associations; the MCP does not read or write a person's private bookmarks.

Run the Python package locally#

The Python distribution is named getbible-mcp; its import package is getbible_mcp. Use Python 3.11 or later. An isolated environment gives the MCP client an explicit executable and keeps dependencies separate from system Python.

python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install getbible-mcp
.venv/bin/getbible-mcp --version
.venv/bin/getbible-mcp --transport stdio

This installs the published package and its compatible dependencies. For production applications, record the tested release in your dependency lockfile and review package releases before updating. Running the stdio command directly waits for protocol input; it is normally launched by an MCP host.

For a per-user executable managed by pipx:

pipx install getbible-mcp
command -v getbible-mcp

In a client using the conventional mcpServers configuration, a PATH-resolved executable looks like this:

{
  "mcpServers": {
    "getbible": {
      "command": "getbible-mcp",
      "args": ["--transport", "stdio"]
    }
  }
}

If a desktop host cannot resolve that command, use the absolute executable path returned by command -v or by realpath .venv/bin/getbible-mcp for a virtual environment. The host's working directory and PATH may differ from your terminal. Let it launch the installed command directly. Standard output is reserved for MCP messages; diagnostics belong on standard error.

Local stdio still reads the configured upstream GetBible services. It does not download a full offline Bible automatically. Ordinary Python applications that want scripture without an MCP host can use the Librarian or call the REST APIs.

Call the remote MCP from Python#

Installing getbible-mcp also installs its supported official Python MCP SDK. This example uses the SDK's Client interface and delegates discovery, protocol metadata and transport handling to the library.

python3 -m venv .venv
.venv/bin/python -m pip install getbible-mcp

Save the following as query_getbible.py and run .venv/bin/python query_getbible.py:

import asyncio
import json

from mcp import Client
from mcp.client.streamable_http import streamable_http_client


async def main() -> None:
    async with Client(
        streamable_http_client("https://mcp.getbible.net/"), cache=None
    ) as client:
        result = await client.call_tool(
            "query_verses",
            {
                "translation": "kjv",
                "references": "John 3:16-19",
                "api_version": "v3",
            },
        )
        if result.is_error:
            raise RuntimeError("GetBible returned an MCP tool error; inspect the result in your client.")
        if result.structured_content is None:
            raise RuntimeError("GetBible returned no structured result.")
        print(json.dumps(result.structured_content, ensure_ascii=False, indent=2))


if __name__ == "__main__":
    asyncio.run(main())

An HTTP 200 response alone does not establish a successful tool lookup: check the MCP error flag. Preserve the structured result's native data, source and cache fields. Applications should also handle transport exceptions and rate limits. Python connection example.

Host or embed your own MCP server#

The package can expose Streamable HTTP locally:

.venv/bin/getbible-mcp --transport streamable-http

With default settings, this listens at http://127.0.0.1:3100/mcp. This is the package's local default, distinct from the official remote root endpoint. Supply that exact URL to a local Inspector. Your application owns HTTPS termination, process management and public hosting.

For direct Python embedding, save this as serve_getbible.py after installing the package:

import uvicorn

from getbible_mcp import create_app


app = create_app(path="/mcp")


if __name__ == "__main__":
    uvicorn.run(app, host="127.0.0.1", port=3100)

Run it with .venv/bin/python serve_getbible.py. create_app returns an ASGI application; create_runtime additionally exposes the server, upstream client and resolved settings. Importing the package creates no default client or network request. If mounting the app inside another ASGI application, the parent must enter child.router.lifespan_context(child) during its own lifespan so startup and HTTP-client cleanup run correctly. Architecture and embedding.

Trusted upstream configuration#

Environment variable	Default upstream
GETBIBLE_API_V2_BASE	https://api.getbible.net/v2
GETBIBLE_API_V3_BASE	https://api.getbible.net/v3
GETBIBLE_QUERY_V2_BASE	https://query.getbible.net/v2
GETBIBLE_QUERY_V3_BASE	https://query.getbible.net/v3
GETBIBLE_SEARCH_V2_BASE	https://search.getbible.net/v2
GETBIBLE_SEARCH_V3_BASE	https://search.getbible.net/v3
GETBIBLE_DICTIONARIES_BASE	https://dictionaries.getbible.net/v1
GETBIBLE_COMMENTARIES_BASE	https://commentaries.getbible.net/v1
GETBIBLE_BOOKMARKS_BASE	https://bookmarks.getbible.net/v1

Mirror URLs must implement the corresponding versioned contract and end in its version path. These are trusted operator settings; a tool caller cannot redirect requests to a different host.

Other controls include GETBIBLE_MCP_BIND_HOST (default 127.0.0.1), GETBIBLE_MCP_BIND_PORT (3100), GETBIBLE_MCP_REQUEST_TIMEOUT (20 seconds), GETBIBLE_MCP_MAX_RESPONSE_BYTES (33,554,432 bytes), and GETBIBLE_MCP_MAX_PARALLEL_HASH_CHECKS (10). Configure host and origin allowlists for a custom public deployment with GETBIBLE_MCP_ALLOWED_HOSTS and GETBIBLE_MCP_ALLOWED_ORIGINS. These memory, timeout and security settings do not change upstream access quotas. Configuration reference.

Discovery resources and integration prompt#

MCP resource or prompt	Purpose
getbible://docs/api	Complete integration guidance
getbible://docs/cache-policy	Expiry, hashes and synchronization
getbible://docs/usage-policy	Public access, limits and content rights
getbible://docs/study-workflows	Dictionary and commentary procedures
getbible://openapi/{service}/{version}	A complete bundled OpenAPI document
design_getbible_integration	Prompt for planning an integration

For example, getbible://openapi/search/v3 identifies the search v3 contract. These are MCP resource identifiers, read through the connected client rather than a normal web browser. The website's corresponding REST guides link to the upstream OpenAPI JSON documents as well.

Freshness and content integrity#

The MCP does not keep an upstream result cache and recommends using query and search responses directly. If your application caches an eligible response, its key must include service, version, operation and every effective input, including translation, filters and page offset.

Honor Cache-Control, Age, response dates and Expires. A shorter remaining lifetime wins. no-store prohibits persistence; no-cache requires revalidation. Never retain content beyond 30 days without refreshing it. An unchanged checksum does not restart that lifetime.

Bible .sha files use SHA-1. Dictionary and commentary hashes.json manifests and bookmark checksums.json use SHA-256. Compare the checksum belonging to the exact scope or document path. A changed translation invalidates its cached books and chapters; a changed book invalidates its chapters. Fetch replacements into temporary storage and replace the old record atomically.

get_scripture checks the scope hash before and after retrieving JSON, retrying once if publication changes during the read. This consistency check is separate from verifying downloaded bytes and from publisher identity. Query results do not carry an invented chapter-hash envelope. Search query.sha describes the source translation, not the result payload. Complete cache policy.

Test a connection#

Use MCP Inspector to discover and call tools with the actual transport:

npx @modelcontextprotocol/inspector@latest

Select Streamable HTTP and enter https://mcp.getbible.net/. For an installed local package:

npx @modelcontextprotocol/inspector@latest \
  .venv/bin/getbible-mcp --transport stdio

Discover tools, call discover_apis, inspect an operation schema, query a known passage, and verify errors for invalid inputs. The repository includes a bounded, explicit endpoint probe for contributors:

git clone https://github.com/getbible/mcp.git getbible-mcp
cd getbible-mcp
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements-dev.txt
.venv/bin/python -m pip install --no-deps -e .
.venv/bin/python scripts/check_endpoint.py
.venv/bin/python scripts/check_endpoint.py --upstreams

The optional upstream check performs representative read-only requests across all nine contracts. It is not a full production load test. Use --expect-version only when checking a known deployment target. A browser GET may wait on a protocol event stream, and /healthz only identifies the running package; actual MCP calls establish whether lookups work.

Troubleshooting#

Symptom	What to check
Connection fails at /mcp or /v3	The official URL is https://mcp.getbible.net/. Remove added path segments.
Browser request hangs	Use an MCP client or Inspector; the endpoint is a protocol service and may stream.
A documented tool is missing	Refresh the connection's tools and metadata, confirm the tool is enabled in your client, then start a new conversation.
HTTP 429	Honor Retry-After, back off and reduce concurrency. See access policy.
HTTP 200 but no useful data	Inspect MCP isError and the structured error; transport success does not mean the upstream lookup succeeded.
Invalid or unresolved reference	Correct the reference or translation. No fallback passage should be substituted.
Dictionary term not found	Discover the right source/language, search its index, retain exact IDs and check all relevant pages. There is no definition-text search endpoint.
Commentary misses a requested verse	Inspect actual coverage and every entry's verses array, including ranges anchored at earlier verses.
Local command not found	Configure the absolute installed executable path in the MCP host and confirm Python 3.11+.
Local protocol output is malformed	Keep application logs on stderr and stdout exclusively for MCP messages.
Embedded application fails at startup	Run the child ASGI lifespan from the parent application.
Whole module or translation is too large	Prefer chapters or individual entries and respect the configured response-size limit.

For public help with any GetBible project, use the single support desk. For credentials or private questions, email [email protected]. Preserve translation and module licenses when displaying or redistributing content; the MCP software license does not relicense those materials.