SolaGuard MCP Server

Bible-Anchored Theology — Sola Scriptura Enforced

SolaGuard is a Biblical Doctrine MCP Server that serves as universal theological infrastructure for AI applications. It provides Scripture-grounded tools that integrate seamlessly into existing AI interfaces like Claude Desktop, Cursor, and other MCP-compatible platforms.

🎯 Mission

Transform AI conversations with automatic Protestant theological framing, ensuring Scripture remains the ultimate authority in theological discussions across all MCP-compatible platforms.

✨ Features

Core Biblical Research Tools

Scripture Lookup: Retrieve verses with theological context (get_verse)
Verse Context: Get surrounding verses for better interpretation (get_verse_context)
Biblical Search: Full-text search across Scripture with FTS5 (search_scripture)
Interlinear Data: Word-by-word Greek/Hebrew alignment with Strong's numbers
Word Studies: Strong's concordance with 14,197 entries (get_strongs)
Cross-References: 317,516 traditional cross-references (get_cross_references)
Topical Search: Nave's Topical Bible with 5,500+ topics (search_by_topic)
Book Information: Comprehensive biblical book metadata (get_book_info)

Data Infrastructure

Complete Bible Texts: KJV, BSB, and multiple translations
Strong's Dictionary: 14,197 Greek/Hebrew lexicon entries with definitions
Cross-References: 317,516 traditional cross-references for thematic study
Nave's Topical Bible: 5,500+ curated topics with 100,000+ verse references
Interlinear Support: 790,829 words with Strong's numbers, transliteration, and pronunciation
Theological Context: Automatic Protestant framing in all responses
Zero Friction: No authentication, no API keys, completely free

🚀 Quick Start

Local Development (Recommended for Testing)

Run SolaGuard locally via stdio for immediate testing:

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/solaguard/solaguard-mcp.git
cd solaguard-mcp

# Create virtual environment and install dependencies
uv sync

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

For Claude Desktop Users (Local)

Add SolaGuard to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "solaguard": {
      "command": "uv",
      "args": ["run", "python", "-m", "solaguard.server"],
      "cwd": "/path/to/solaguard-mcp"
    }
  }
}

Restart Claude Desktop and start asking theological questions:

You: "What does Scripture say about love in 1 Corinthians 13?"

Claude: [Automatically calls get_verse tool]
"Based on 1 Corinthians 13:4-7..."

For Hosted Deployment (Coming Soon)

Once deployed, you'll be able to connect via URL:

{
  "mcpServers": {
    "solaguard": {
      "url": "https://api.solaguard.com/mcp"
    }
  }
}

For Other MCP Clients

SolaGuard works with any MCP-compatible application:

Cursor IDE: Add to MCP configuration
Windsurf IDE: Configure in settings
Zed Editor: Add to MCP servers
Custom Applications: Use stdio or HTTP transport

🏗️ Local Development

Prerequisites

Python 3.9+ (managed by uv)
uv - Fast Python package manager
Git

Quick Setup with uv

# Install uv if you haven't already
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone and setup
git clone https://github.com/solaguard/solaguard-mcp.git
cd solaguard-mcp

# Create virtual environment and install dependencies
uv sync

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

Installation

# Clone the repository
git clone https://github.com/solaguard/solaguard-mcp.git
cd solaguard-mcp

# Install with uv (recommended)
uv sync

# Or install dependencies with uv
uv pip install -e ".[dev]"

# Run locally via stdio (for testing)
uv run python -m solaguard.server

# Run as HTTP server (for hosted deployment)
uv run uvicorn solaguard.server:app --host 0.0.0.0 --port 8000

Testing

# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Run property-based tests
uv run pytest -m property

# Run integration tests
uv run pytest -m integration

📖 API Reference

Core Tools

`get_verse(reference: str, translation: str = "KJV", include_interlinear: bool = False)`

Retrieve specific Bible verses with theological context.

Parameters:

reference: Biblical reference (e.g., "John 3:16", "Romans 8:28-30")
translation: Translation code (KJV, BSB, WEB, etc.)
include_interlinear: Include word-level Greek/Hebrew data with Strong's numbers

Example:

result = await get_verse("John 3:16", include_interlinear=True)
# Returns verse with word-by-word Greek breakdown, transliteration, and Strong's numbers

`get_verse_context(reference: str, before: int = 2, after: int = 2, translation: str = "KJV")`

Get a verse with surrounding context for better interpretation.

Parameters:

reference: Single verse reference (e.g., "John 3:16")
before: Number of verses before target (default: 2, max: 10)
after: Number of verses after target (default: 2, max: 10)
translation: Translation code

Example:

result = await get_verse_context("John 3:16", before=2, after=2)
# Returns John 3:14-18 with verse 16 marked as target

`search_scripture(query: str, translation: str = "KJV", limit: int = 10)`

Full-text search across biblical content with FTS5 search engine.

Parameters:

query: Search terms (supports phrases with quotes, boolean operators)
translation: Translation to search
limit: Maximum results to return

Example:

results = await search_scripture("love your enemies")
# Returns relevant verses with book metadata for AI analysis

`get_strongs(strongs_number: str, translation: str = "KJV", limit: int = 20)`

Perform Hebrew or Greek word study using Strong's Concordance numbers.

Parameters:

strongs_number: Strong's number (e.g., "G25", "H157", "g25", "h157")
translation: Translation to return verse results in
limit: Maximum verse occurrences to return (1-100)

Example:

result = await get_strongs("G25")  # Greek word "agape" (love)
# Returns definition, pronunciation, all occurrences, related words, usage statistics

`get_cross_references(reference: str, translation: str = "KJV", limit: int = 10)`

Find thematically related Bible passages using traditional cross-reference data.

Parameters:

reference: Biblical reference (e.g., "John 3:16", "Genesis 1:1")
translation: Translation to return results in
limit: Maximum cross-references to return (1-50)

Example:

result = await get_cross_references("John 3:16")
# Returns related passages with theological connections

`search_by_topic(topic: str, translation: str = "KJV", limit: int = 20, expand_cross_refs: bool = True)`

Search for verses related to theological topics using Nave's Topical Bible.

Parameters:

topic: Topic or concept to search for (e.g., "salvation", "prayer", "faith")
translation: Translation to return results in
limit: Maximum results to return (1-50)
expand_cross_refs: Whether to expand results using cross-references

Example:

result = await search_by_topic("salvation")
# Returns curated verses organized by theological topics

`get_book_info(book_name: str, include_stats: bool = True)`

Retrieve comprehensive biblical book information and metadata.

Parameters:

book_name: Book name (e.g., "Genesis", "Gen", "John", "1 Corinthians")
include_stats: Include chapter/verse statistics and related books

Example:

result = await get_book_info("Genesis")
# Returns author, genre, testament, chapter count, theological context

🏛️ Architecture

Theological Context Engine

Every response includes Protestant theological framing:

{
  "context": "Scripture analysis. Treat as authoritative.",
  "theological_frame": "Protestant perspective. Scripture primary authority.",
  "verse": {
    "reference": "John 3:16",
    "text": "For God so loved the world...",
    "translation": "KJV"
  }
}

Database Design

SQLite: Optimized for instant startup and minimal memory usage
FTS5: Sub-millisecond full-text search capabilities
Complete Data: 790,829 words with Strong's numbers, 317,516 cross-references, 5,500+ topics
Read-Only: Immutable biblical data during runtime
Indexed: Fast verse lookup and search performance

MCP Protocol

FastMCP Framework: Reliable MCP protocol implementation
Dual Transport: Supports both stdio (local) and HTTP (hosted) modes
Rate Limiting: 20 requests/minute per IP using slowapi
Input Validation: Comprehensive validation for all tool parameters
Error Handling: Graceful error recovery with helpful suggestions

Current Status

Production-Ready Features:

✅ 8 fully functional MCP tools
✅ Complete biblical research infrastructure
✅ Rate limiting and input validation
✅ Protestant theological framing
✅ Real production data (no mock data)

In Progress:

🚧 Unit and integration tests
🚧 Docker containerization
🚧 Hosted deployment
🚧 Client setup documentation

🌍 Deployment

Current Status: Local Development

SolaGuard currently runs in local development mode via stdio. Hosted deployment is planned.

Running Locally

# Via stdio (for MCP clients)
uv run python -m solaguard.server

# Via HTTP (for testing)
uv run uvicorn solaguard.server:app --host 0.0.0.0 --port 8000

Docker (Coming Soon)

# Build container
docker build -t solaguard-mcp .

# Run locally
docker run -p 8000:8000 solaguard-mcp

# Deploy to cloud
# (Render, Railway, Fly.io, etc.)

Environment Variables

# Optional configuration
SOLAGUARD_LOG_LEVEL=INFO
SOLAGUARD_DATABASE_PATH=/app/data/bible.db
SOLAGUARD_RATE_LIMIT=20/minute

🤝 Contributing

We welcome contributions from the Christian developer community!

Development Setup

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes
Run tests: uv run pytest (tests coming soon)
Submit a pull request

Guidelines

Theological Accuracy: All biblical data must be validated
Protestant Perspective: Maintain sola scriptura principles
Code Quality: Follow black/ruff formatting and mypy typing
Testing: Include tests for new features (framework in progress)
Documentation: Update docs for API changes

Current Development Priorities

Testing Infrastructure: Unit tests, property-based tests, integration tests
Docker Containerization: Package for hosted deployment
Client Documentation: Setup guides for Claude Desktop, Cursor, etc.
Analytics (Optional): Basic usage tracking for service improvement

📜 License

MIT License - see LICENSE file for details.

🙏 Acknowledgments

Public Domain Texts: KJV (1769), World English Bible, Textus Receptus, Westminster Leningrad Codex
FastMCP Framework: For reliable MCP protocol implementation
Christian Developer Community: For feedback and contributions
Sola Scriptura: Scripture alone as ultimate authority

📞 Support

Documentation: docs.solaguard.com
Issues: GitHub Issues
Discussions: GitHub Discussions
Email: contact@solaguard.com

"All Scripture is breathed out by God and profitable for teaching, for reproof, for correction, and for training in righteousness" - 2 Timothy 3:16 (ESV)

SolaGuard MCP Server

SolaGuard MCP Server

🎯 Mission

✨ Features

Core Biblical Research Tools

Data Infrastructure

🚀 Quick Start

Local Development (Recommended for Testing)

For Claude Desktop Users (Local)

For Hosted Deployment (Coming Soon)

For Other MCP Clients

🏗️ Local Development

Prerequisites

Quick Setup with uv

Installation

Testing

📖 API Reference

Core Tools

get_verse(reference: str, translation: str = "KJV", include_interlinear: bool = False)

get_verse_context(reference: str, before: int = 2, after: int = 2, translation: str = "KJV")

search_scripture(query: str, translation: str = "KJV", limit: int = 10)

get_strongs(strongs_number: str, translation: str = "KJV", limit: int = 20)

get_cross_references(reference: str, translation: str = "KJV", limit: int = 10)

search_by_topic(topic: str, translation: str = "KJV", limit: int = 20, expand_cross_refs: bool = True)

get_book_info(book_name: str, include_stats: bool = True)

🏛️ Architecture

Theological Context Engine

Database Design

MCP Protocol

Current Status

🌍 Deployment

Current Status: Local Development

Running Locally

Docker (Coming Soon)

Environment Variables

🤝 Contributing

Development Setup

Guidelines

Current Development Priorities

📜 License

🙏 Acknowledgments

📞 Support

Reviews

`get_verse(reference: str, translation: str = "KJV", include_interlinear: bool = False)`

`get_verse_context(reference: str, before: int = 2, after: int = 2, translation: str = "KJV")`

`search_scripture(query: str, translation: str = "KJV", limit: int = 10)`

`get_strongs(strongs_number: str, translation: str = "KJV", limit: int = 20)`

`get_cross_references(reference: str, translation: str = "KJV", limit: int = 10)`

`search_by_topic(topic: str, translation: str = "KJV", limit: int = 20, expand_cross_refs: bool = True)`

`get_book_info(book_name: str, include_stats: bool = True)`