📚 정보나루 도서검색 MCP (data4library-mcp)

도서관 정보나루 MCP는 국립중앙도서관에서 제공하는 도서관 정보나루 API를 완전히 활용할 수 있도록 개발된 포괄적인 MCP(Model Context Protocol) 서버입니다. 한국의 모든 공공도서관 정보, 도서 검색, 대출 현황, 독서 통계 등을 AI 모델에서 쉽게 접근하고 활용할 수 있게 해줍니다.

🇺🇸 English Documentation: README-en.md

🚀 빠른 설치 (Smithery 권장)

가장 쉬운 설치 방법은 Smithery를 사용하는 것입니다:

**🔗 Smithery에서 설치하기**

1. 위 링크를 클릭하여 Smithery 페이지로 이동

2. "Install" 버튼 클릭

3. API 키 입력 (아래 API 키 발급 방법 참조)

4. Claude Desktop에서 바로 사용 가능!

🌟 도서관 정보나루(Data4Library)란?

도서관 정보나루는 국립중앙도서관이 운영하는 전국 공공도서관 통합 정보 서비스입니다. 전국 1,000여 개 공공도서관의 실시간 데이터를 통합하여 제공하며, 다음과 같은 정보를 포함합니다:

📍 전국 공공도서관 위치 및 운영정보 (1,000+ 개관)
📖 도서 소장 및 대출 현황 (실시간)
📊 대출 통계 및 트렌드 분석
🔥 인기도서 및 급상승 도서
📈 지역별/연령별 독서량 통계
🆕 신착도서 정보

🎯 주요 기능 (25개 도구)

📚 도서관 & 도서 검색

🏛️ 전국 공공도서관 검색 (search_libraries): 지역별, 도서관명으로 검색
📖 도서 통합 검색 (search_books): 제목, 저자, 출판사, 주제별 도서 검색
🔍 도서관별 소장도서 검색 (search_libraries_by_book): 특정 도서를 소장한 도서관 찾기
📋 도서 상세정보 (get_book_detail): ISBN으로 상세 정보 조회
✅ 대출 가능 여부 (check_book_availability): 실시간 대출 가능 상태 확인

📊 인기도서 & 트렌드 분석

🔥 인기 대출도서 (search_popular_books): 전국/지역별 베스트셀러
🏆 도서관별 인기도서 (search_popular_books_by_library): 특정 도서관의 인기도서
📈 대출 급상승 도서 (get_hot_trend): 트렌딩 도서 실시간 조회
🆕 신착도서 (get_new_arrival_books): 도서관별 새로 들어온 도서
🏷️ 이달의 키워드 (get_monthly_keywords): 독서 트렌드 키워드

📈 통계 & 분석 도구

📊 대출반납 추이 (get_usage_trend): 도서관별 이용 통계 그래프
🌍 지역별 독서량 (get_reading_quantity): 독서율 및 독서량 비교
📚 장서/대출 데이터 (search_items): 도서관별 상세 통계
📖 도서 이용 분석 (get_book_usage_analysis): 특정 도서의 이용 패턴

🎯 개인화 추천 시스템

🎓 마니아 추천도서 (get_mania_recommendations): 전문가용 심화 도서
📚 다독자 추천도서 (get_reader_recommendations): 연속 독서용 도서
🏷️ 도서 키워드 분석 (get_book_keywords): 도서별 핵심 키워드

🗺️ 위치 기반 서비스 (독자적 구현)

📍 내 주변 도서관 검색 (search_nearby_libraries): GPS 기반 가까운 도서관 자동 검색
거리순 정렬: 실시간 거리 계산 및 가까운 순서로 정렬
상세 거리 정보: 각 도서관까지의 정확한 거리(km) 표시

🔧 코드 검색 도구 (API 연동 지원)

🏛️ 도서관 코드 검색 (search_library_codes): 도서관명으로 libCode 찾기
🌍 지역코드 조회 (get_region_codes, get_detailed_region_codes): 전국/세부 지역코드
📚 주제분류코드 (get_subject_codes, get_detailed_subject_codes): KDC 대/세분류
📊 통합정보 조회 (get_library_info, get_popular_books_by_library): 도서관별 종합 정보

🛠️ 세션 관리

📊 사용량 통계 (session_stats): 실시간 도구 호출 통계 및 세션 정보

💡 실제 사용 시나리오

🔍 도서관 찾기

"내 주변 도서관 어디 있어?" → search_nearby_libraries 사용
"서울 강남구 도서관 찾아줘" → search_detailed_region_codes + search_libraries 순차 사용

📖 도서 검색

"해리포터 책 어디서 빌릴 수 있어?" → search_books + search_libraries_by_book 연계
"김영하 작가 소설 찾아줘" → search_books (저자명 검색)

📊 트렌드 분석

"요즘 인기 있는 책 뭐야?" → search_popular_books 또는 get_hot_trend
"강남도서관에서 인기 있는 책" → search_library_codes + search_popular_books_by_library

📈 통계 분석

"서울 사람들이 책을 얼마나 많이 읽어?" → get_reading_quantity
"도서관 이용 그래프 보여줘" → get_usage_trend

🎯 복합 쿼리 예시

"내 주변 도서관들의 신간 도서 현황"

1. search_nearby_libraries (위치 기반 도서관 검색)

2. get_new_arrival_books (각 도서관별로 신간 조회)

"강남구 도서관에서 경제서적 인기 순위 보여줘"

1. search_detailed_region_codes (강남구 코드 조회)

2. get_subject_codes (경제 분야 코드 조회)

3. search_popular_books_by_library (필터 적용하여 검색)

🚀 기술적 특징

✅ 완전한 API 래핑: 도서관 정보나루 API 25개 엔드포인트 전체 지원
🔗 스마트 체이닝: 도구 간 자동 연계로 복잡한 쿼리 처리
⚡ 실시간 데이터: 도서관 정보나루와 실시간 동기화
🗺️ 위치 기반 알고리즘: 자체 구현한 Haversine 공식 기반 거리 계산 및 정렬
🛡️ Zod 스키마 검증: 모든 입력값 타입 안전성 보장
📊 세션 통계: 도구 사용량 실시간 모니터링
🔧 오류 처리: 상세한 로깅 및 디버깅 정보
🎯 시나리오 기반 설명: LLM이 상황에 맞는 도구를 쉽게 선택할 수 있도록 구체적인 사용 시나리오 제공

🎬 활용 사례

🏛️ 시민/기관 포털

동네 도서관 현황 및 운영 정보 챗봇
신간/인기도서 알림 서비스

🎓 교육/연구

KDC 주제별 독서 트렌드 분석
연령/지역별 독서 통계 리포트

📈 출판/마케팅

인기 장르/도서 발굴 (연령/성별/지역별)
트렌드 변화 모니터링

📱 앱/서비스

ISBN 기반 실시간 소장/대출 가능 여부 UX
위치 기반 도서관 추천

🚀 시작하기

1️⃣ 전제 조건

Node.js 18+
도서관 정보나루 API 키

2️⃣ API 키 발급 방법

1. 도서관 정보나루 회원가입

2. 로그인 후 우상단 [마이페이지] 클릭

3. 마이페이지 메뉴에서 인증키 선택

4. 적절한 이용목적 체크 및 개인정보 수집 이용 동의 체크

5. 수정완료 버튼 클릭

6. 상태가 승인대기중으로 표시 - 승인까지 시간 소요

7. 승인 후 발급된 API 키를 복사하여 환경변수에 저장

💡 참고: 승인 처리에 시간이 걸릴 수 있습니다. 보통 신청 후 익일 오전에 승인됩니다.

📊 API 호출 제한

기본: 하루 500회 제한
IP 등록 후: 하루 30,000회 제한

IP 등록 방법: 마이페이지 → 인증키 관리에서 서버IP 필드에 MCP 서버가 실행될 컴퓨터의 IP 주소를 입력하면 호출 제한이 500회에서 30,000회로 확대됩니다.

⚠️ 중요: 2023년 11월 20일부터 무제한 호출이 중단되었으며 최대 제한은 하루 30,000회입니다.

3️⃣ 환경 변수 설정

LIBRARY_API_KEY (필수): 도서관 정보나루에서 발급받은 API 키

Windows PowerShell (현재 세션용):

powershell

$env:LIBRARY_API_KEY="your-api-key"

macOS/Linux:

bash

export LIBRARY_API_KEY="your-api-key"

📦 설치 방법

Installing via Smithery

To install data4library-mcp automatically via Smithery:

bash

npx -y @smithery/cli install @isnow890/data4library-mcp

방법 1: NPX 설치 (권장)

가장 쉬운 방법은 NPX를 통한 설치입니다. 자세한 패키지 정보는 NPM 패키지 페이지를 참조하세요.

Claude Desktop 설정

Claude Desktop 설정 파일 (Windows: %APPDATA%\Claude\claude_desktop_config.json, macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json)에 다음을 추가:

json

{
  "mcpServers": {
    "data4library-mcp": {
      "command": "npx",
      "args": ["-y", "@isnow890/data4library-mcp"],
      "env": {
        "LIBRARY_API_KEY": "your-api-key"
      }
    }
  }
}

Cursor AI 설정

mcp.json에 추가:

json

{
  "mcpServers": {
    "data4library-mcp": {
      "command": "npx",
      "args": ["-y", "@isnow890/data4library-mcp"],
      "env": {
        "LIBRARY_API_KEY": "your-api-key"
      }
    }
  }
}

방법 2: 로컬 설치

로컬 개발이나 커스텀 수정을 위한 설치:

Step 1: 소스코드 다운로드 및 빌드

##### Git으로 클론

bash

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

##### ZIP 파일 다운로드

1. GitHub Releases 페이지에서 최신 버전 다운로드

2. ZIP 파일을 원하는 위치에 압축 해제

3. 터미널에서 압축 해제된 폴더로 이동:

bash

cd /path/to/data4library-mcp
npm install
npm run build

⚠️ 중요: 설치 후 반드시 npm run build를 실행하여 dist 폴더에 컴파일된 JavaScript 파일들을 생성해야 합니다.

Step 2: Claude Desktop 설정

빌드 완료 후 필요한 것들:

LIBRARY_API_KEY: 도서관 정보나루에서 발급받은 API 키
설치 경로: 다운로드한 폴더의 절대 경로

##### Windows 설정

Claude Desktop 설정 파일 (%APPDATA%\Claude\claude_desktop_config.json)에 다음을 추가:

json

{
  "mcpServers": {
    "data4library-mcp": {
      "type": "stdio",
      "command": "cmd",
      "args": [
        "/c",
        "node",
        "C:\\path\\to\\data4library-mcp\\dist\\src\\index.js"
      ],
      "cwd": "C:\\path\\to\\data4library-mcp",
      "env": {
        "LIBRARY_API_KEY": "your-api-key"
      }
    }
  }
}

##### macOS/Linux 설정

Claude Desktop 설정 파일 (~/Library/Application Support/Claude/claude_desktop_config.json)에 다음을 추가:

json

{
  "mcpServers": {
    "data4library-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/data4library-mcp/dist/src/index.js"],
      "cwd": "/path/to/data4library-mcp",
      "env": {
        "LIBRARY_API_KEY": "your-api-key"
      }
    }
  }
}

##### 경로 설정 주의사항

⚠️ 중요: 위 설정에서 다음 경로들을 실제 설치 경로로 바꿔주세요:

Windows: C:\\path\\to\\data4library-mcp를 실제 다운로드한 폴더 경로로 변경
macOS/Linux: /path/to/data4library-mcp를 실제 다운로드한 폴더 경로로 변경
빌드 경로: 경로가 dist/src/index.js를 가리키도록 확인 (단순히 index.js가 아님)

경로 찾기:

bash

# 현재 위치 확인
pwd

# 절대 경로 예시
# Windows: C:\Users\YourName\Downloads\data4library-mcp
# macOS: /Users/YourName/Downloads/data4library-mcp
# Linux: /home/YourName/Downloads\data4library-mcp

Step 3: Claude Desktop 재시작

설정 완료 후 Claude Desktop을 완전히 종료하고 재시작하여 Data4Library MCP 서버를 활성화하세요.

🔧 로컬 실행 (개발/테스트용)

Claude Desktop 통합 없이 직접 실행하기:

bash

npm start
# 또는
node dist/src/index.js

Docker (선택사항):

bash

docker build -t data4library-mcp .
docker run -i --rm -e LIBRARY_API_KEY=$LIBRARY_API_KEY data4library-mcp

MCP 클라이언트 통합 (.mcp.json 예시, 로컬 실행):

json

{
  "mcpServers": {
    "data4library-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["dist/src/index.js"],
      "env": {
        "LIBRARY_API_KEY": "your-api-key"
      }
    }
  }
}

💡 사용 팁

퍼지 검색: search_library_codes를 사용하여 부분 이름/주소로 도서관 찾기
코드 헬퍼: get_subject_codes, search_detailed_kdc_codes, search_detailed_region_codes로 필요한 파라미터 코드 조회
세션 모니터링: session_stats로 세션별 도구 사용량/제한 확인
도구 연계: 복잡한 쿼리는 여러 도구를 순차적으로 사용하여 해결

📝 라이선스 및 고지사항

라이선스: MIT (LICENSE 파일 참조)
데이터 출처: 도서관 정보나루 공공 API
사용법: 공공 API 정책/할당량을 준수하세요. 개인정보를 저장/노출하지 마세요.

---

💬 질문이나 피드백이 있으시면 GitHub 이슈를 열어주세요!

Data4library Mcp

Documentation

📚 정보나루 도서검색 MCP (data4library-mcp)

🚀 빠른 설치 (Smithery 권장)

🌟 도서관 정보나루(Data4Library)란?

🎯 주요 기능 (25개 도구)

📚 도서관 & 도서 검색

📊 인기도서 & 트렌드 분석

📈 통계 & 분석 도구

🎯 개인화 추천 시스템

🗺️ 위치 기반 서비스 (독자적 구현)

🔧 코드 검색 도구 (API 연동 지원)

🛠️ 세션 관리

💡 실제 사용 시나리오

🔍 도서관 찾기

📖 도서 검색

📊 트렌드 분석

📈 통계 분석

🎯 복합 쿼리 예시

🚀 기술적 특징

🎬 활용 사례

🏛️ 시민/기관 포털

🎓 교육/연구

📈 출판/마케팅

📱 앱/서비스

🚀 시작하기

1️⃣ 전제 조건

2️⃣ API 키 발급 방법

📊 API 호출 제한

3️⃣ 환경 변수 설정

📦 설치 방법

Installing via Smithery

방법 1: NPX 설치 (권장)

Claude Desktop 설정

Cursor AI 설정

방법 2: 로컬 설치

Step 1: 소스코드 다운로드 및 빌드

Step 2: Claude Desktop 설정

Step 3: Claude Desktop 재시작

🔧 로컬 실행 (개발/테스트용)

💡 사용 팁

📝 라이선스 및 고지사항

Similar MCP

Metmuseum Mcp

Mcp Ipfs

Mcp Open Library

Anilist Mcp

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Metmuseum Mcp

Mcp Ipfs

Mcp Open Library

Anilist Mcp

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare