圣经经文检索 MCP 服务器

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.

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.

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

• mcp-service-kit
• FastMCP Documentation
• Docker setup

License

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