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:

1. Create feature directory: features/my_feature/
2. Add instructions.md: Comprehensive documentation in markdown
3. Add tool.py: With register_tool(mcp, service) function using @inject_docstring
4. 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

• Using mcp-weather as Dependency
• Main mcp-weather README
• FastMCP Documentation
• FastAPI Documentation

License

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