kairos_codex_mcp_server

Kairos Codex MCP Server exposes a set of tools to access Bible data via the Model Context Protocol. The server acts as a tool provider for LLMs, returning JSON-structured results for translations, books, verses, and entire chapters. Use get_translations to fetch available translations with optional language filtering, then drill down with get_books to see the books in a translation. For targeted queries, use get_verses to retrieve specific verses (by translation, book, chapter, and verse range) or get_chapter to obtain all verses within a chapter. Each tool returns structured objects with translation details, book metadata, and the requested verse data, along with consistent error handling. If configured, the server can require a simple token for access control, supplied via the BIBLE_SERVER_TOKEN environment variable.

Prerequisites:

• Python 3.11+
• Internet access to install dependencies

Step 1: Clone the repository (or download the project files).

Step 2: Create and activate a Python environment (optional but recommended):

• Python venv: python -m venv venv source venv/bin/activate # Unix/macOS venv\Scripts\activate # Windows

Step 3: Install dependencies:

• pip install -r requirements.txt

Step 4: Optional configuration for authentication:

• Set a token via environment variable or .env file as described in the README: export BIBLE_SERVER_TOKEN=your_token_here or Create a .env file with: BIBLE_SERVER_TOKEN=your_token_here

Step 5: Run the server:

• Direct Python execution: python bible.py

Step 6: (Optional) Run with Docker:

• docker-compose up --build
• Or build and run manually: docker build -t kairos-codex-mcp . docker run -p 8000:8000 kairos-codex-mcp

Step 7: Verify the server is running by sending a test request to the MCP endpoint (e.g., /get_translations).

Tips and caveats:

• The server uses httpx for HTTP requests to the Bible API and provides JSON responses with structured error data.
• If no token is set, authentication is disabled. When enabled, include the token via the BIBLE_SERVER_TOKEN environment variable or .env file.
• Docker users: the README provides docker-compose and manual docker commands; ensure port 8000 is available if using the manual run.
• If you encounter issues, check that Python 3.11+ is in use and that network access to https://bible.helloao.org is available.
• The tools assume standard MCP parameter shapes; when integrating with an LLM, format prompts to supply translation_id, book, chapter, and verse ranges as described in the tool docs.