Overview

This MCP (Model Context Protocol) server provides a developer-friendly proxy to South Korea’s Library Information Naru API. It wraps library data and operations — book search, loan status checks, reading statistics, and GPS-based public library discovery — behind a consistent REST/MCP interface so client applications can integrate library services without talking directly to Naru.

The server is useful for building mobile apps, web portals, or backend services that need unified access to Korean public library data. It normalizes parameters, handles authentication to the upstream Naru API, and implements location-based search helpers (find nearby libraries by coordinates) to simplify common developer tasks.

Features

Unified REST/MCP endpoints for:
- Book search (title, author, ISBN)
- Loan/status lookup for patrons
- Reading and usage statistics
- Nearby public library discovery via GPS
Parameter normalization and paging
Example client-ready JSON responses suitable for use with MCP-aware tools
Lightweight deployment: runs locally or in containers
Useful for location-aware apps and library search integrations

Installation / Configuration

Clone the repository and install dependencies (Node.js example). Replace environment values with credentials you obtain from the library/Naru authority.

Clone and install

git clone https://github.com/isnow890/data4library-mcp.git
cd data4library-mcp
npm install

Create a .env file (example)

PORT=3000
NODE_ENV=production
NARU_API_KEY=your_naru_api_key_here
DEFAULT_RADIUS=5000   # meters

Run the server

# development
npm run dev

# production
npm start

Docker (optional)

# docker-compose.yml (example)
version: '3'
services:
  mcp-server:
    image: your-registry/data4library-mcp:latest
    ports:
      - "3000:3000"
    environment:
      - PORT=3000
      - NARU_API_KEY=your_naru_api_key_here

docker-compose up -d

Configuration notes:

NARU_API_KEY is required to forward requests to the upstream Library Information Naru API.
PORT controls the listening port; change as needed for your environment.
DEFAULT_RADIUS sets a fallback search radius for GPS-based queries.

Available Resources

GitHub repository: https://github.com/isnow890/data4library-mcp
MCP-compatible endpoints (documented below)
Example client scripts and curl snippets in the repo to get started quickly

API Endpoints (Common)

Endpoint	Method	Description	Parameters
/search/books	GET	Search books by title, author, ISBN	q (query), isbn, page, size
/loans	POST	Check patron loan status	libraryCode, patronId, secret (or token)
/reading/stats	GET	Retrieve reading or circulation stats	libraryCode, startDate, endDate
/libraries/nearby	GET	Find public libraries near GPS coordinates	lat, lng, radius (meters)

Note: Parameter names may be normalized from upstream Naru API formats. Authentication to the server can be implemented per your deployment (API keys, tokens).

Use Cases and Examples

Example 1 — Book search (title):

curl "http://localhost:3000/search/books?q=해리포터&page=1&size=10"

Example response (abridged):

{
  "total": 125,
  "items": [
    { "title": "해리 포터와 마법사의 돌", "author": "J.K. Rowling", "isbn": "9781234567890", "available": true },
    ...
  ]
}

Example 2 — Check loans for a patron:

curl -X POST "http://localhost:3000/loans" \
  -H "Content-Type: application/json" \
  -d '{"libraryCode":"100001","patronId":"P12345678","secret":"****"}'

Response:

{
  "patronId": "P12345678",
  "loans": [
    { "title":"도서명 A", "dueDate":"2026-05-12", "status":"on-loan" }
  ]
}

Example 3 — Find nearby public libraries:

curl "http://localhost:3000/libraries/nearby?lat=37.5665&lng=126.9780&radius=2000"