Bible MCP Server

A Model Context Protocol (MCP) server that provides Bible passage retrieval functionality using the mcp-weather core infrastructure.

This server enables AI assistants to access Bible passages from various translations, with support for multiple deployment modes:

--mode stdio (default): MCP protocol over stdin/stdout for direct AI assistant integration
--mode mcp: MCP protocol over HTTP for networked AI assistant access
--mode rest: Both REST API and MCP protocol over HTTP for maximum flexibility

Features

The Bible MCP Server provides:

MCP Tools (for AI assistants)

get_passage(passage, version) - Retrieve Bible passages. Supports multiple passages separated by semicolons (e.g., "John 3:16; Romans 8:28").

REST API Endpoints

GET /health - Health check
GET /info - Service information
POST /passage - Get Bible passage
GET /docs - OpenAPI documentation (Swagger UI)

Supported Bible Versions

ESV (English Standard Version)
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)

Installation

Prerequisites

Python 3.10+
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
uv sync

Step 2: Configure Environment

# Copy example configuration
cp .env.example .env

# Edit .env with your settings
vi .env

Usage

The Bible MCP server supports three deployment modes via command-line arguments:

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

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

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

Perfect for direct integration with AI assistants like GitHub Copilot, Claude Desktop, etc.

Mode 2: mcp - MCP Protocol over HTTP

# MCP-only server on HTTP (no REST API)
uv run mcp-bible --mode mcp --port 3000 --no-auth

Provides MCP protocol over HTTP at http://localhost:3000/mcp for networked AI assistant access.

Mode 3: rest - Full HTTP Server (REST + MCP)

# Full server with both REST API and MCP protocol
uv run mcp-bible --mode rest --port 3000 --no-auth

The server will start at http://localhost:3000 with:

MCP endpoint: http://localhost:3000/mcp
REST API: http://localhost:3000/*
API docs: http://localhost:3000/docs
Health check: http://localhost:3000/health

Test the MCP Tools

You can test the MCP tools by connecting GitHub Copilot or using a test 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"

Test the REST API

# Health check
curl http://localhost:3000/health

# Get service info
curl http://localhost:3000/info

# Get a Bible passage
curl -X POST "http://localhost:3000/passage" \
  -H "Content-Type: application/json" \
  -d '{
    "passage": "John 3:16",
    "version": "ESV"
  }'

# Get multiple passages
curl -X POST "http://localhost:3000/passage" \
  -H "Content-Type: application/json" \
  -d '{
    "passage": "John 3:16; Romans 8:28; Philippians 4:13",
    "version": "NIV"
  }'

# Get an entire chapter
curl -X POST "http://localhost:3000/passage" \
  -H "Content-Type: application/json" \
  -d '{
    "passage": "Mark 2",
    "version": "ESV"
  }'

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 stdio            # stdio mode
uv run mcp-bible --mode mcp --port 4000  # MCP-only HTTP on port 4000
uv run mcp-bible --mode rest --port 4000 # REST+MCP HTTP on port 4000
uv run mcp-bible --mode rest --no-auth   # Disable authentication

Environment Variables (Alternative to CLI)

You can also configure the server using environment variables:

# Alternative: Set environment variables
export MCP_TRANSPORT=http        # stdio or http
export MCP_ONLY=false           # true for MCP-only, false for REST+MCP
export MCP_HOST=0.0.0.0         # Host to bind to
export MCP_PORT=3000            # Port number
export AUTH_ENABLED=false       # Enable/disable authentication

# Then run without arguments
uv run mcp-bible

Test All Modes

Run the comprehensive test suite:

uv run tests/test_modes.py

Or try the interactive curl examples:

./examples/curl_examples.sh

Project Structure

mcp_bible/
├── __init__.py              # Package metadata
├── config.py                # Configuration management (extends mcp-weather core)
├── bible_service.py         # Business logic (Bible API client)
├── service.py               # MCP service wrapper (with automatic feature discovery)
├── server.py                # Server implementation (CLI mode support)
├── features/                # Feature modules (MODULAR PATTERN)
│   ├── __init__.py
│   └── get_passage/         # Get passage feature
│       ├── __init__.py
│       ├── instructions.md  # 📝 Comprehensive documentation (core.utils)
│       ├── models.py        # Feature-specific models
│       ├── tool.py          # MCP tool definition (uses @inject_docstring)
│       └── routes.py        # REST API endpoints (uses load_instruction)
├── shared/                  # Shared models and utilities
│   ├── __init__.py
│   └── models.py            # Base models, error types
├── tests/                   # Test suite
│   └── test_modes.py        # Mode support testing
└── examples/                # Usage examples
    └── curl_examples.sh     # Interactive REST API examples

Core.utils Integration

This project uses the core.utils pattern from mcp-weather for dynamic documentation:

instructions.md: Comprehensive feature documentation in markdown
@inject_docstring: Dynamically injects markdown into MCP tool docstrings
load_instruction: Loads markdown for REST API documentation
Single source of truth: Same documentation for both MCP tools and REST endpoints

How It Works

Features Pattern (Automatic Discovery)

This server uses automatic feature discovery - just like mcp-weather!

Add a new feature in 4 steps:

Create feature directory: features/my_feature/
Add instructions.md: Comprehensive documentation in markdown
Add tool.py: With register_tool(mcp, service) function using @inject_docstring
Add routes.py (optional): With create_router(service) function using load_instruction

Example feature structure:

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

@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}

# features/my_feature/routes.py  
from core.utils import load_instruction

@router.post("/endpoint", description=load_instruction("instructions.md", __file__))
async def endpoint():
    """Same documentation for REST API"""
    return {"data": "value"}

That's it! The service automatically:

Discovers your feature
Registers MCP tools from tool.py
Includes REST routes from routes.py
Loads documentation from instructions.md

No manual registration needed!

1. Configuration Layer (config.py)

Extends core configuration classes with service-specific settings:

from core.config import BaseServerConfig

class BibleAPIConfig(BaseModel):
    base_url: str
    supported_versions: List[str]

class AppConfig(BaseModel):
    server: ServerConfig
    bible_api: BibleAPIConfig

2. Business Logic Layer (bible_service.py)

Pure business logic, independent of MCP/REST:

class BibleService:
    async def fetch_passage(self, passage: str, version: str) -> dict:
        # Bible passage retrieval logic here
        ...

3. MCP Service Wrapper (service.py)

Implements BaseService to expose business logic via MCP:

from core.server import BaseService

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

4. Server Implementation (server.py)

Extends BaseMCPServer to create the complete server:

from core.server import BaseMCPServer

class BibleMCPServer(BaseMCPServer):
    @property
    def service_title(self) -> str:
        return "Bible MCP Server"

    def create_router(self) -> APIRouter:
        # Add REST endpoints
        ...

Key Benefits of Using mcp-weather Core

By using mcp-weather as a dependency, you get:

✅ No boilerplate - Server infrastructure is ready to use
✅ Multiple deployment modes - stdio, MCP-only HTTP, REST+MCP HTTP via CLI
✅ Dynamic documentation - Markdown-based docs via core.utils
✅ Dual interfaces - MCP + REST API automatically
✅ Configuration - Environment variable management
✅ Error handling - Comprehensive exception handling
✅ Type safety - Full Pydantic models and type hints
✅ Async support - Async-first design throughout
✅ Logging - Structured logging built-in
✅ CORS - Configurable CORS support
✅ Health checks - Standard endpoints
✅ Testing - Comprehensive test suite included

Customization

Add New MCP Tools

Edit mcp_bible/service.py:

def register_mcp_tools(self, mcp: FastMCP) -> None:
    @mcp.tool()
    async def my_new_tool(param: str) -> dict:
        """Tool description for AI"""
        return {"result": "value"}

Add New REST Endpoints

Edit mcp_bible/server.py:

def create_router(self) -> APIRouter:
    router = APIRouter()

    @router.get("/my-endpoint")
    async def my_endpoint():
        return {"data": "value"}

    return router

Add New Configuration

Edit mcp_bible/config.py:

class BibleAPIConfig(BaseModel):
    my_new_field: str = Field(default="value")

Troubleshooting

Import Errors

Make sure you're importing from core, not mcp_weather.core:

from core.server import BaseMCPServer  # ✅ Correct
from mcp_weather.core.server import BaseMCPServer  # ❌ Wrong

Module Not Found

Make sure mcp-weather is installed:

uv pip list | grep mcp-weather

If not installed, install it:

uv sync  # Installs from pyproject.toml

Features Implemented ✅

✅ Multiple deployment modes (stdio, mcp, rest)
✅ CLI interface with comprehensive help
✅ Dynamic documentation using core.utils
✅ Bible passage retrieval from BibleGateway.com
✅ 8 Bible translations supported
✅ Multiple passage support (semicolon-separated)
✅ Comprehensive test suite with mode testing
✅ REST API examples and curl scripts
✅ Auto-discovery of features
✅ Structured logging throughout

Next Steps

Add authentication providers (Authentik integration)
Add more Bible API sources (Bible API, ESV API)
Implement passage search and concordance
Add daily verses and reading plans
Add Redis caching for performance
Add metrics and monitoring
Add Docker deployment examples

Learn More

License

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