# 📖 BibleGateway Verse of the Day — MCP Server

> *"Thy word is a lamp unto my feet, and a light unto my path."* — Psalm 119:105 (KJV)

A **Model Context Protocol (MCP) server** that delivers the daily Word of God — sourced directly from [BibleGateway.com](https://www.biblegateway.com) — into any MCP-compatible AI development environment. This project was built to make Scripture accessible through modern AI tooling, ensuring that the Gospel of Jesus Christ can reach developers, researchers, and everyday users wherever they work.

**No API key is required.** The BibleGateway VOTD endpoint is a free, publicly accessible web service.

---

## ✝️ Mission

This server exists not merely as a software utility, but as a vessel for the Great Commission. By integrating the living Word of God into AI-assisted workflows, developers may begin each session anchored in Scripture. Whether used in a personal devotional context or as a reference tool in professional environments, this MCP server ensures that the Gospel of Jesus Christ is never more than one tool-call away — available in over 300 translations across dozens of languages, reaching every nation and tongue.

---

## 🌍 What This Server Does

Each Python script in this repository is a standalone FastMCP server exposing one or more Bible translation tools. Each tool fetches the **Verse of the Day (VOTD)** from BibleGateway for a specific Bible version and returns a structured JSON response.

### Included Scripts

| Script | Languages / Scope |
|---|---|
| `biblegateway-votd.py` | Primary: KJV, NIV, ESV, NLT, Arabic, Japanese, Chinese, Russian, French, and more |
| `biblegateway-votd-basic.py` | Core English translations (KJV, AMP, MSG, CSB, ESV, NIV, NLT) |
| `biblegateway-votd-english.py` | Full English translation suite (40+ versions) |
| `biblegateway-votd-spanish.py` | Spanish translations (RVR, NVI, NTV, etc.) |
| `biblegateway-votd-alternate-languages.py` | Global translations: Arabic, Bulgarian, Bengali, Cherokee, Thai, Ukrainian, Yoruba, and dozens more |

---

## ⚙️ Installation

This project uses [`uv`](https://docs.astral.sh/uv/getting-started/installation/) for environment and dependency management, following the [MCP Quickstart for Server Developers](https://modelcontextprotocol.io/quickstart/server).

```bash
# 1. Clone the repository
git clone https://github.com/cmathgit/biblegateway-votd-mcp.git

# 2. Initialize the project
uv init biblegateway-votd-mcp
cd biblegateway-votd-mcp

# 3. Create and activate the virtual environment
uv venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

# 4. Install dependencies
uv add mcp[cli] httpx
```

### Test a Server Locally

```bash
uv run biblegateway-votd.py
```

---

## 🔧 MCP Configuration

Add the server to your IDE's MCP configuration file (`mcp.json`). Supported IDEs include **Cursor**, **Roo Code**, **Cline**, and **Gemini-CLI**.

```json
{
  "mcpServers": {
    "biblegateway-votd": {
      "command": "/ABSOLUTE/PATH/TO/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/biblegateway-votd-mcp",
        "run",
        "biblegateway-votd.py"
      ]
    }
  }
}
```

> **Note for Cursor users:** Cursor limits the combined length of server name + tool name to 60 characters. If tools fail to load, abbreviate the server name in `mcp.json`.

> **Recommendation:** Load only the scripts containing the Bible versions you actively need. Some IDEs cap the total number of registered MCP tools in global context.

---

## 💬 Usage Examples

Once the server is running, query it through your AI agent using natural language:
```
What is the verse of the day in the King James Version?
What is the verse of the day in the Nueva Versión Internacional?
What is the verse of the day in the bible version with ID: 278?
What is the verse of the day in the Pobitro Bible?
```


All tools accept zero arguments and return a structured JSON payload from BibleGateway.

---

## 🔗 References

- [BibleGateway VOTD API Documentation](https://www.biblegateway.com/share/#versehtml)
- [Full Bible Version & ID List](https://www.biblegateway.com/usage/linking/versionslist/)
- [Model Context Protocol Documentation](https://modelcontextprotocol.io/quickstart/server)
- [uv Package Manager](https://docs.astral.sh/uv/)

---

## 📄 License

MIT License — © 2025 Cruz Macias. See [LICENSE](./LICENSE) for details.