Skip to main content
Glama
Bible MCP Server

Bible MCP Server

by geosp

Bible MCP Server

A Model Context Protocol (MCP) server that provides Bible passage retrieval, built on mcp-service-kit.

This server lets AI assistants read Bible passages from various translations. It runs in two modes:

  • --mode stdio (default): MCP over stdin/stdout, for local AI assistant integration

  • --mode http: MCP over streamable HTTP at /mcp, for networked access

Features

MCP Tools (for AI assistants)

  • get_passage(passage, version): retrieves Bible passages. Pass several references separated by semicolons (e.g., "John 3:16; Romans 8:28") to get them all at once. If version is omitted, the configured default (ESV) is used.

Bible Versions

version is passed to BibleGateway as-is, so any version abbreviation it offers works (e.g. ESV, NIV, KJV, NASB, LSB); there is no list to maintain here. See BibleGateway's versions page. If a version isn't available, the tool returns success: false with the error.

Related MCP server: bible-mcp

Installation

Prerequisites

  • Python 3.11+

  • uv package manager

Installing uv

On Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

On Windows:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Alternatively, you can install uv using pip:

pip install uv

After installation, restart your terminal or run source ~/.bashrc (Linux/macOS) or restart your command prompt (Windows).

Step 1: Install Dependencies

# From this directory
cd mcp-bible

# Install dependencies (including mcp-service-kit from GitHub)
uv sync

Step 2: Configure Environment (optional)

# Copy example configuration
cp .env.example .env

# Edit .env with your settings
vi .env

Usage

Mode 1: stdio (Default) - Local AI Assistant Integration

# Default mode - MCP over stdin/stdout
uv run mcp-bible

# Explicitly specify stdio mode
uv run mcp-bible --mode stdio

Use this mode to integrate directly with AI assistants such as GitHub Copilot or Claude Desktop.

Mode 2: http - MCP over HTTP

uv run mcp-bible --mode http --port 3000 --no-auth

This serves MCP at http://localhost:3000/mcp for networked AI assistants.

No authentication provider is configured, so HTTP mode needs --no-auth (or MCP_AUTH_ENABLED=false). Without it, mcp-service-kit refuses to start rather than serve the tools unauthenticated. To protect the endpoint, override create_auth_provider() in mcp_bible/server.py (see Authentication in the kit's README).

Connect an MCP Client

You can test the MCP tools by connecting GitHub Copilot or another MCP client:

// .vscode/mcp.json
{
  "servers": {
    "bible": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

Then ask Copilot:

  • "Show me John 3:16"

  • "What does Romans 8 say?"

  • "Read Psalm 23 in NIV"

To debug interactively, run npx @modelcontextprotocol/inspector and point it at either transport.

CLI Help and Options

# See all available options
uv run mcp-bible --help

# Usage examples:
uv run mcp-bible                                  # stdio mode (default)
uv run mcp-bible --mode http --no-auth --port 4000          # HTTP on port 4000
uv run mcp-bible --mode http --no-auth --log-level DEBUG    # verbose logging

Environment Variables

Settings are read from the environment and from .env. Command-line flags take precedence.

Variable

Default

Description

MCP_TRANSPORT

stdio

Transport: stdio or http (--mode)

MCP_HOST

0.0.0.0

Host to bind to in HTTP mode (--host)

MCP_PORT

3000

Port in HTTP mode (--port)

MCP_AUTH_ENABLED

true

Require an auth provider in HTTP mode; set false (or --no-auth) to serve without one

BIBLE_API_URL

https://www.biblegateway.com/passage/

BibleGateway passage URL

BIBLE_DEFAULT_VERSION

ESV

Version used when none is requested

BIBLE_TIMEOUT

30

HTTP request timeout in seconds

Testing

# Unit and in-memory MCP tests (offline; BibleGateway is mocked)
uv run pytest

Live smoke test against a running HTTP server (this calls BibleGateway.com):

uv run mcp-bible --mode http --port 3000 --no-auth &
uv run python examples/client_example.py "John 3:16"
uv run python examples/client_example.py --url http://localhost:4000/mcp "Romans 8:28"

Project Structure

mcp_bible/
├── __init__.py              # Package metadata (version)
├── config.py                # Configuration (BibleAPIConfig + kit's BaseServerConfig)
├── bible_service.py         # Business logic (BibleGateway client and parser)
├── service.py               # MCP service wrapper (automatic feature discovery)
├── server.py                # Server and CLI entry point (mcp-service-kit)
└── features/                # Feature modules
    ├── __init__.py
    └── get_passage/         # Get passage feature
        ├── __init__.py
        ├── instructions.md  # Tool documentation (injected into the docstring)
        ├── models.py        # Feature-specific models
        └── tool.py          # MCP tool definition (uses @inject_docstring)
tests/                       # pytest suite
examples/
└── client_example.py        # Live MCP client smoke test

How It Works

Features Pattern (Automatic Discovery)

BibleMCPService discovers every package under features/ and calls the register_tool(mcp, bible_service) function in its tool.py.

Add a new feature in 3 steps:

  1. Create feature directory: features/my_feature/

  2. Add instructions.md: The tool's documentation in markdown

  3. Add tool.py: With a register_tool(mcp, service) function

# features/my_feature/tool.py
from mcp_service_kit.utils import inject_docstring, load_instruction


def register_tool(mcp, bible_service):
    @mcp.tool()
    @inject_docstring(lambda: load_instruction("instructions.md", __file__))
    async def my_tool(param: str) -> dict:
        """Documentation loaded from instructions.md"""
        return {"result": param}

You don't need to register anything by hand.

1. Configuration Layer (config.py)

Each section is a pydantic-settings model that reads its own environment variables:

from mcp_service_kit import BaseServerConfig

class BibleAPIConfig(BaseSettings):      # BIBLE_* variables
    api_url: str
    default_version: str

class AppConfig(BaseModel):
    server: BaseServerConfig              # MCP_* variables
    bible_api: BibleAPIConfig

2. Business Logic Layer (bible_service.py)

Business logic that knows nothing about MCP:

class BibleService:
    def __init__(self, api_config: BibleAPIConfig): ...

    async def fetch_passage(self, passage: str, version: str | None = None) -> dict:
        ...

3. MCP Service Wrapper (service.py)

Implements the kit's BaseService to expose the business logic via MCP:

from mcp_service_kit import BaseService

class BibleMCPService(BaseService):
    def register_mcp_tools(self, mcp: FastMCP) -> None:
        # Automatic feature discovery and registration

4. Server Implementation (server.py)

Extends the kit's BaseMCPServer and builds the CLI with create_main_with_modes:

from mcp_service_kit import BaseMCPServer, create_main_with_modes

class BibleMCPServer(BaseMCPServer):
    service_title = ...        # plus service_description, service_version

main = create_main_with_modes(
    BibleMCPServer, create_bible_service, AppConfig, "mcp-bible", "..."
)

Customization

Add New Configuration

Edit mcp_bible/config.py:

class BibleAPIConfig(BaseSettings):
    my_new_field: str = Field(default="value")   # read from BIBLE_MY_NEW_FIELD

Add Middleware or Auth

BibleMCPServer can override the kit's hooks: instructions, create_middleware() (e.g. FastMCP's ResponseCachingMiddleware), create_auth_provider() and validate_configuration(). See Server hooks.

Next Steps

  • Add authentication (e.g. a JWTVerifier for Authentik via create_auth_provider())

  • Add more Bible API sources (Bible API, ESV API)

  • Implement passage search and concordance

  • Add daily verses and reading plans

  • Add Redis caching (mcp-service-kit[redis])

  • Add metrics and monitoring

Learn More

License

This project is provided as-is for use and modification.

Available Tools

1 tool
get_passageA

Bible Passage Retrieval Tool

Get Bible passages from multiple translations with automatic content parsing and cleaning.

This tool retrieves Bible passages from BibleGateway.com, supporting multiple Bible versions and passage formats. The content is automatically cleaned and formatted for easy reading.

Legal Notice: All Bible text content is sourced from BibleGateway.com. All copyright, licensing, and other legal concerns regarding the Bible translations and text content are covered by BibleGateway.com's terms of service and licensing agreements with the respective publishers. This tool serves as an interface to publicly available content and respects all applicable copyright restrictions.

Parameters

passage (required)

  • Type: string

  • Description: Bible reference(s) to retrieve

  • Format: Book Chapter:Verse or Book Chapter

  • Examples:

    • "John 3:16" - Single verse

    • "John 3:16-21" - Verse range

    • "John 3" - Entire chapter

    • "Mark 2:1-12" - Specific verse range

    • "John 3:16; Romans 8:28" - Multiple references

version (optional)

  • Type: string

  • Default: "ESV"

  • Description: Bible translation version

  • Supported versions: ESV, NIV, KJV, NASB, NKJV, NLT, AMP, MSG

Usage Examples

Single verse:

{
  "passage": "John 3:16",
  "version": "NIV"
}

Chapter range:

{
  "passage": "Mark 2:1-12",
  "version": "ESV"
}

Entire chapter:

{
  "passage": "Psalm 23",
  "version": "KJV"
}

Multiple passages:

{
  "passage": "John 3:16; Romans 8:28; Philippians 4:13",
  "version": "ESV"
}

Response Format

Returns a structured response containing:

  • success: Whether the request was successful

  • passage: The requested Bible reference

  • version: The Bible version used

  • text: The passage text (cleaned and formatted)

  • error: Error message if request failed

Supported Bible Versions

  • ESV - English Standard Version (default)

  • NIV - New International Version

  • KJV - King James Version

  • NASB - New American Standard Bible

  • NKJV - New King James Version

  • NLT - New Living Translation

  • AMP - Amplified Bible

  • MSG - The Message

When to Use This Tool

  • Scripture study and research

  • Sermon preparation and biblical analysis

  • Cross-referencing verses across translations

  • Gathering biblical supporting material

  • Comparing different translation renderings

Content Processing

The tool automatically:

  • Removes HTML formatting and ads

  • Cleans up spacing and formatting

  • Preserves verse numbers and structure

  • Handles chapter headings appropriately

  • Supports multi-passage requests

Content Source: All Bible text is retrieved from BibleGateway.com (https://www.biblegateway.com/)

Copyright Protection: BibleGateway.com handles all copyright, licensing, and legal compliance for Bible translations. Each translation (ESV, NIV, KJV, etc.) has specific copyright holders and licensing terms that are managed and enforced by BibleGateway.com.

Fair Use: This tool accesses publicly available content through BibleGateway.com's web interface for educational, research, and personal study purposes. All copyright and licensing obligations are covered by BibleGateway.com's agreements with publishers.

Compliance: Users should be aware that while this tool provides access to Bible content, all legal responsibilities regarding copyright, attribution, and proper use remain with the respective copyright holders as managed by BibleGateway.com.

Inputs: passage (required), version. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusion or overlap between tools. The tool 'get_passage' has a clearly defined and singular purpose of retrieving Bible passages, making disambiguation perfect.

    Naming Consistency5/5

    Since there is only one tool, naming consistency is inherently perfect. The tool name 'get_passage' follows a clear verb_noun pattern, but with no other tools to compare, consistency is not applicable in a meaningful way.

    Tool Count2/5

    A single tool for a Bible server is too minimal for the domain's scope. While 'get_passage' handles retrieval well, typical Bible-related tasks like searching, comparing translations, or accessing metadata are missing, making the tool count feel insufficient and limiting for comprehensive use.

    Completeness2/5

    The server is severely incomplete for a Bible domain. It only provides passage retrieval, lacking essential operations such as search, cross-referencing, translation comparison, or access to book/chapter lists. This creates significant gaps that will hinder agents in performing common Bible study tasks.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      Provides structured access to Scripture through the BibleBridge API, enabling semantic search, contextual verse retrieval, and cross-reference analysis. It supports natural language reference normalization and comparative theological exploration across different passages.
      1
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to look up Bible verses, search across translations, and compare different versions locally without API keys.
      1
      -
    • A
      license
      A
      quality
      B
      maintenance
      Free, no-key MCP server for reading scripture from 35+ public-domain translations in 8 languages. Lets users fetch verses, chapters, and passages via natural language from any MCP client.
      7
      67 npm
      1
      MIT