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 both MCP protocol support and REST API endpoints.

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

Run in MCP-only Mode (stdio)

# Set transport to stdio in .env
export MCP_TRANSPORT=stdio
export MCP_ONLY=true

# Run the server
uv run python -m mcp_bible.server

Run in HTTP Mode with REST API

# Set transport to HTTP in .env
export MCP_TRANSPORT=http
export MCP_ONLY=false
export MCP_PORT=3000

# Run the server
uv run python -m mcp_bible.server

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"
  }'

Project Structure

mcp_bible/
├── __init__.py              # Package metadata
├── config.py                # Configuration management
├── bible_service.py         # Business logic (Bible API client)
├── service.py               # MCP service wrapper (with feature discovery)
├── server.py                # Server implementation
├── features/                # Feature modules (MODULAR PATTERN)
│   ├── __init__.py
│   ├── get_passage/         # Get passage feature
│   │   ├── __init__.py
│   │   ├── models.py        # Feature-specific models
│   │   ├── tool.py          # MCP tool definition
│   │   └── routes.py        # REST API endpoints
└── shared/                  # Shared models and utilities
    ├── __init__.py
    └── models.py            # Base models, error types

How It Works

Features Pattern (Automatic Discovery)

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

Add a new feature in 3 steps:

1. Create feature directory: features/my_feature/
2. Add tool.py: With register_tool(mcp, service) function
3. Add routes.py (optional): With create_router(service) function

That's it! The service automatically:

• Discovers your feature
• Registers MCP tools from tool.py
• Includes REST routes from routes.py

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 ✅ 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

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

Next Steps

• Add real Bible API integration
• Add more Bible versions
• Implement passage search
• Add daily verses
• Implement caching
• Add metrics and monitoring

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.