# Bible MCP Server

A public MCP (Model Context Protocol) server that provides Bible verse lookup and search capabilities, powered by a custom Bible API hosted on Cloudflare Workers with D1.

**Documentation:** https://tuxr.github.io/bible-mcp
**MCP Endpoint:** `https://bible-mcp.dws-cloud.com/mcp`

## Features

- 📖 **Get Verse** - Retrieve any verse, range, or chapter
- 🔍 **Search Bible** - Full-text search with book/testament filters
- 📚 **List Books** - Browse all 86 books including Apocrypha
- 🌍 **Multiple Translations** - WEB, KJV, WLC Hebrew, and more
- 🎲 **Random Verse** - With optional book/testament filters

## Available Tools

| Tool | Description |
|------|-------------|
| `get_verse` | Fetch verses by reference (e.g., "John 3:16", "Psalm 23", "Romans 8:28-39", "Romans 14:14, 22-23") |
| `get_chapter` | Get a full chapter with navigation hints for sequential reading |
| `search_bible` | Search for words/phrases with book and testament filters |
| `list_books` | List Bible books with chapter counts, filterable by testament |
| `list_translations` | Show available translations |
| `get_random_verse` | Get a random verse, optionally filtered by book or testament |

## Supported Translations

- `web` - World English Bible (default)
- `kjv` - King James Version
- `wlc` - Westminster Leningrad Codex (Hebrew Old Testament)

Use `list_translations` to see all available translations.

## Development

### Prerequisites

- Node.js 18+
- A Cloudflare account (for deployment)

### Setup

```bash
npm install
npm run dev
```

Your MCP server will be running at `http://localhost:8787/mcp`

### Testing with MCP Inspector

```bash
npm run inspect
```

Then enter `http://localhost:8787/mcp` in the inspector.

## Deployment

```bash
npm run deploy
```

## Connecting to Claude.ai

1. Go to Claude.ai Settings → Connectors
2. Add the MCP server URL: `https://bible-mcp.dws-cloud.com/mcp`
3. The Bible tools will now be available in your conversations

## Cursor / Agent Plugin

This repository is an [Agent Plugin](https://agent-plugins.org/) (`plugin.json` + `mcp.json` + `skills/`). It does **not** start a local MCP process or wrap the REST API. Cursor loads the skill and connects to the **hosted** Streamable HTTP endpoint:

`https://bible-mcp.dws-cloud.com/mcp`

No API key is required.

### Install from this repo (local plugin path)

1. Clone or use a local checkout of this repository.
2. Point Cursor at it as a local plugin (symlink or copy):

```bash
ln -s /path/to/bible-mcp ~/.cursor/plugins/local/bible-mcp
```

3. Restart Cursor, or run **Developer: Reload Window**.
4. In **Customize**, confirm the `bible-mcp` plugin: skill `scripture-lookup` and MCP server `bible`.

On Teams/Enterprise, local plugin imports may need to be enabled by an admin.

## Example Usage

Once connected, you can ask Claude things like:

- "Look up John 3:16"
- "Read Romans 14:14, 22-23" (comma-separated with context inheritance)
- "Search the Bible for 'faith' in the New Testament"
- "Show me a random Psalm"
- "List the books of the Apocrypha"
- "Get Romans 8:28-39 in KJV"
- "Read Genesis 1:1 in WLC Hebrew"

## Architecture

```mermaid
graph LR
    Client([Claude.ai]) -->|MCP Protocol| MCP[MCP Worker]
    MCP -->|HTTPS or Service Binding| API[Bible API]
    API -->|SQL| D1[(D1 Database)]
```

- **MCP Server:** Cloudflare Worker with MCP protocol handler
- **Bible API:** REST API providing verse data ([GitHub](https://github.com/tuxr/bible-api))
- **Database:** Cloudflare D1 with 74,000+ verses
- **Search:** Full-text search via FTS5 index

### API Connection Options

The MCP server can connect to the Bible API in two ways:

| Option | Use Case | Configuration |
|--------|----------|---------------|
| **Public API** | Use the hosted API, or deploy to a different Cloudflare account | Set `BIBLE_API_URL` in wrangler.toml |
| **Service Binding** | Both workers in the same Cloudflare account (faster) | Configure `[[services]]` in wrangler.toml |

**Using the public API (default):**
```toml
[vars]
BIBLE_API_URL = "https://bible-api.dws-cloud.com"
```

**Using a service binding (same account):**
```toml
[[services]]
binding = "BIBLE_API"
service = "your-bible-api-worker-name"  # Your worker's name
```

> **Note:** The `binding` must be `BIBLE_API` (this matches the code). The `service` is whatever you named your Bible API worker when you deployed it.

## License

MIT