# Bible Korean MCP Server
[](https://github.com/oksure/bible-ko-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/bible-ko-mcp)
[](https://opensource.org/licenses/MIT)
MCP (Model Context Protocol) server for accessing the Korean Bible from bskorea.or.kr.
**Features:**
- โก๏ธ **In-memory caching** with 30-min TTL for fast repeated requests
- ๐ก๏ธ **Robust error handling** with try/catch and graceful fallbacks
- โ
**Input validation** with Zod schemas
- ๐ฅ **Health check** tool for monitoring
- ๐ **All 66 books** with 5 translations supported
- ๐ **Full-text search** across entire Bible
## Node.js Version
Requires **Node.js 20+**
## Features
This MCP server provides tools to:
- Get complete chapters from the Korean Bible
- Retrieve specific verses or verse ranges
- Search for verses containing keywords
- List all available books
- Compare verses across different Korean translations
## Installation
Install globally via npm:
```bash
npm install -g bible-ko-mcp
```
Or use directly with npx (no installation required):
```bash
npx -y bible-ko-mcp
```
## Available Tools
### 1. `get-chapter`
Get all verses from a specific chapter.
**Parameters:**
- `book` (string, required): Book name in English, Korean, or book code
- Examples: "Genesis", "์ฐฝ์ธ๊ธฐ", "gen"
- `chapter` (number, required): Chapter number
- `version` (string, optional): Bible translation version (default: "GAE")
- Options: "GAE", "GAE1", "NIR", "KOR", "CEV"
**Example:**
```json
{
"book": "Genesis",
"chapter": 1,
"version": "GAE"
}
```
### 2. `get-verses`
Get specific verse(s) from a chapter.
**Parameters:**
- `book` (string, required): Book name or code
- `chapter` (number, required): Chapter number
- `verseStart` (number, required): Starting verse number
- `verseEnd` (number, optional): Ending verse number (defaults to verseStart)
- `version` (string, optional): Bible translation version (default: "GAE")
**Example:**
```json
{
"book": "John",
"chapter": 3,
"verseStart": 16,
"verseEnd": 17,
"version": "GAE"
}
```
### 3. `search-bible`
Search for verses containing specific keywords.
**Parameters:**
- `query` (string, required): Search query in Korean or English
- `version` (string, optional): Bible translation version (default: "GAE")
**Note:** Search covers all 66 books of the Bible with fallback results.
**Example:**
```json
{
"query": "์ฌ๋",
"version": "GAE"
}
```
### 4. `list-books`
List all available books in the Bible.
**Parameters:**
- `testament` (string, optional): Filter by testament ("OT" or "NT")
**Example:**
```json
{
"testament": "NT"
}
```
### 5. `compare-translations`
Compare a verse across different Korean translations.
**Parameters:**
- `book` (string, required): Book name or code
- `chapter` (number, required): Chapter number
- `verse` (number, required): Verse number
- `versions` (array, optional): Array of version codes to compare (default: all versions)
**Example:**
```json
{
"book": "John",
"chapter": 3,
"verse": 16,
"versions": ["GAE", "NIR", "KOR"]
}
```
## Bible Translations
- **GAE**: ๊ฐ์ญ๊ฐ์ (Revised Korean Standard Version)
- **GAE1**: ๊ฐ์ญํ๊ธ (Korean Revised Version)
- **NIR**: ์๋ฒ์ญ์ฑ๊ฒฝ (New Korean Revised Version)
- **KOR**: ๊ณต๋๋ฒ์ญ (Common Translation)
- **CEV**: CEV (Contemporary English Version)
## Book Codes
### Old Testament
- Genesis (์ฐฝ์ธ๊ธฐ): `gen`
- Exodus (์ถ์ ๊ตฝ๊ธฐ): `exo`
- Leviticus (๋ ์๊ธฐ): `lev`
- Numbers (๋ฏผ์๊ธฐ): `num`
- Deuteronomy (์ ๋ช
๊ธฐ): `deu`
- ... (see full list in source code)
### New Testament
- Matthew (๋งํ๋ณต์): `mat`
- Mark (๋ง๊ฐ๋ณต์): `mrk`
- Luke (๋๊ฐ๋ณต์): `luk`
- John (์ํ๋ณต์): `jhn`
- Acts (์ฌ๋ํ์ ): `act`
- ... (see full list in source code)
## Usage with Claude Desktop
Add to your Claude Desktop configuration:
### macOS
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"bible-ko": {
"command": "npx",
"args": [
"-y",
"bible-ko-mcp"
]
}
}
}
```
### Windows
Edit `%APPDATA%\Claude\claude_desktop_config.json` with the same configuration above.
After adding the configuration, restart Claude Desktop completely.
## Development
For local development:
```bash
# Clone the repository
git clone https://github.com/oksure/bible-ko-mcp.git
cd bible-ko-mcp
# Install dependencies
npm install
# Build
npm run build
# Run tests
npm test
# Watch mode (auto-rebuild on changes)
npm run watch
# Run locally
npm start
```
### Local Development with Claude Desktop
For testing local changes, use this configuration:
```json
{
"mcpServers": {
"bible-ko": {
"command": "node",
"args": [
"/absolute/path/to/bible-ko-mcp/build/index.js"
]
}
}
}
```
Remember to run `npm run build` after making changes.
## Technical Details
- Built with TypeScript and the MCP SDK
- Uses cheerio for HTML parsing
- Fetches data from bskorea.or.kr
- Supports all 66 books of the Bible
- Handles Korean and English book names
## Notes
- The HTML parsing may need adjustment based on website updates
- Search functionality is limited for demo purposes to avoid excessive requests
- Some translations may not be available for all books
## Publishing
This package is automatically published to NPM when a new GitHub release is created. See [PUBLISHING.md](PUBLISHING.md) for detailed instructions.
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
## License
MIT
