# BibleMCP

Production-ready MCP server that lets LLMs explore, analyze, and reason over the Bible using local ChromaDB stores and Mistral embeddings.

## Supported translations

Each translation is stored in its own isolated local Chroma directory (never mixed):

| Alias | helloao ID | Display name |
|-------|------------|--------------|
| `BSB` | `BSB` | Berean Standard Bible |
| `ASV` | `eng_asv` | American Standard Version (1901) |
| `BBE` | `eng_bbe` | Bible in Basic English |
| `KJAV` | `eng_kjv` | King James (Authorized) Version |

## Architecture

```
MCP client (Cursor / Claude Desktop)
        │ stdio
        ▼
  biblemcp/server.py  →  tools  →  services  →  storage (Chroma per translation)
                                      ↓
                              helloao API (ingest)
                              Mistral API (embeddings)
```

## Setup

### 1. Install

```bash
uv sync --extra dev
```

This creates `.venv`, installs the project in editable mode, and adds dev dependencies (pytest).

> **Note:** `onnxruntime` is pinned to `<=1.19.2` because newer releases dropped Intel Mac (`x86_64`) wheels. BibleMCP uses Mistral for embeddings, not Chroma's built-in ONNX embedder — this pin only satisfies ChromaDB's install requirement.

Run project commands through uv without activating the venv:

```bash
uv run biblemcp ingest --help
uv run pytest
uv run python -m biblemcp.server
```

### 2. Configure environment

Copy `.env.example` to `.env` and set your Mistral key:

```bash
cp .env.example .env
```

Required for ingest and semantic search:

- `MISTRAL_API_KEY`

Optional:

- `BIBLEMCP_DATA_DIR` (default `./data/chroma`)
- `BIBLEMCP_DEFAULT_TRANSLATION` (default `BSB`)

### 3. Ingest Bible text

Before semantic tools work, populate the local databases:

```bash
uv run biblemcp ingest --translation BSB
uv run biblemcp ingest --all
```

This fetches text from [helloao](https://bible.helloao.org), embeds verses with `mistral-embed`, and upserts into `data/chroma/{bsb,asv,bbe,kjav}/`.

Re-running ingest is safe (upsert).

## MCP client configuration

### Cursor

Add to your MCP settings:

```json
{
  "mcpServers": {
    "biblemcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/BibleMCP", "run", "python", "-m", "biblemcp.server"],
      "env": {
        "MISTRAL_API_KEY": "your_key",
        "BIBLEMCP_DATA_DIR": "/absolute/path/to/BibleMCP/data/chroma"
      }
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "biblemcp": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/BibleMCP", "run", "python", "-m", "biblemcp.server"],
      "env": {
        "MISTRAL_API_KEY": "your_key",
        "BIBLEMCP_DATA_DIR": "/absolute/path/to/BibleMCP/data/chroma"
      }
    }
  }
}
```

Use absolute paths for `--directory` and `BIBLEMCP_DATA_DIR`. If `uv` is not on your PATH for the MCP host, use the full path to the `uv` binary.

## Screenshots

### Configured in Cursor

Once connected, `biblemcp` shows as active with all 10 tools available:

![BibleMCP configured in Cursor MCP settings](screenshots/configured.png)

### In action

Ask for verses on a theme — the agent searches and fetches passages through the MCP tools:

![Agent searching and fetching passages via BibleMCP](screenshots/usage1.png)

![BibleMCP returning five verses on final judgment](screenshots/usage1-1.png)

## The 10 tools

| Tool | What it does |
|------|----------------|
| `search_verse` | Semantic keyword/phrase search |
| `get_verse` | Exact single-verse lookup |
| `get_passage` | Exact verse range within a chapter |
| `cross_reference` | Semantic neighbors for a reference (not curated TSK) |
| `topic_lookup` | Semantic topic search |
| `original_language_lookup` | Semantic search framed by a term (**not** Strong's) |
| `character_profile` | Relevant verses about a character (**no** biography DB) |
| `timeline_event_lookup` | Relevant verses for an event (**no** date database) |
| `summarize_passage` | Chapter text + instructions for the host LLM to summarize |
| `theological_analysis` | Primary + related passages + question for host LLM analysis |

All tools accept an optional `translation` field (`BSB`, `ASV`, `BBE`, `KJAV`).

## Development

Run tests:

```bash
uv run pytest
```

Run the server locally:

```bash
uv run python -m biblemcp.server
```

CLI help:

```bash
uv run biblemcp ingest --help
```

## Project layout

```
src/biblemcp/
  bible/          # book aliases, reference parsing
  clients/        # helloao + Mistral embeddings
  models/         # Pydantic types
  services/       # ingest, retrieval, search, context
  storage/        # per-translation Chroma store
  tools/          # MCP tool schemas, handlers, registry
  server.py       # FastMCP entrypoint
  cli.py          # ingest CLI
tests/            # unit, service, and tool tests
data/chroma/      # local vector stores (gitignored)
```

## License

Apache-2.0 — see [LICENSE](LICENSE).