Data4library MCP Server

📚 정보나루 도서검색 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 (현재 세션용):

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

macOS/Linux:

export LIBRARY_API_KEY="your-api-key"

📦 설치 방법

Installing via Smithery

To install data4library-mcp automatically via Smithery:

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)에 다음을 추가:

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

Cursor AI 설정

mcp.json에 추가:

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

방법 2: 로컬 설치

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

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

Git으로 클론

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

ZIP 파일 다운로드

1. GitHub Releases 페이지에서 최신 버전 다운로드
2. ZIP 파일을 원하는 위치에 압축 해제
3. 터미널에서 압축 해제된 폴더로 이동:

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)에 다음을 추가:

{
  "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)에 다음을 추가:

{
  "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가 아님)

경로 찾기:

# 현재 위치 확인
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 통합 없이 직접 실행하기:

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

Docker (선택사항):

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

MCP 클라이언트 통합 (.mcp.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 이슈를 열어주세요!