nl-openapi-mcp

국립중앙도서관 대한민국 국가서지 OpenAPI (Seoji OpenAPI) 문헌·도서 서지 메타데이터 검색·수집 MCP 서버 + CLI. 자매 프로젝트 kci-openapi-mcp 및 scienceon-mcp와 동일한 공통 코어(REST/MCP/CLI/Exporter) 아키텍처를 공유합니다.

An MCP server + CLI for National Library of Korea Seoji OpenAPI. Bring your own API key and search & harvest Korean academic literature and book bibliography metadata in any project.

무엇을 할 수 있나

🔎 일반 검색 (kwd) & 상세 검색 (title, author, publisher, keyword, isbn, seoji_year): 국가서지 도서 및 문헌 검색
📄 단건 조회: 제어번호(control_no) 및 URL 경로를 통한 서지사항 확인
💾 대량 수집 & 파일 저장: 검색 결과를 xlsx / csv / json / sqlite 형태로 로컬 내보내기
🤖 두 가지 사용법: Claude에서 도구 호출(MCP) · 터미널 배치(CLI) — 같은 코어 공유

요구사항

Python 3.10+
uv (패키지 관리)
국립중앙도서관 OpenAPI 발급키 (NL_API_KEY)

1) API 키 발급

국립중앙도서관 OpenAPI 안내 페이지에 접속하여 회원가입·로그인
OpenAPI 이용신청 → 대한민국 국가서지 Open API 신청 및 승인 후 API 키 발급
환경변수 NL_API_KEY (또는 프로젝트 내 .env)에 발급키 설정

2) 설치 및 실행

전제: uv 설치 (Windows: winget install astral-sh.uv).

방법 A — uvx (설정 직접, 설치 불필요 - PyPI / Git)

PyPI 정식 등록 후:

uvx nl-openapi-mcp status
uvx nl-openapi-mcp search --kwd "정보"

또는 GitHub 소스에서 실행:

uvx --from git+https://github.com/rubato103/nl-openapi-mcp nl-mcp status

방법 B — 로컬 개발 환경 (OneDrive 동기화 폴더 대응)

클라우드 동기화 폴더 안에서 작업할 경우 가상환경을 외부에 생성합니다:

# Windows (PowerShell/CMD)
set UV_PROJECT_ENVIRONMENT=C:\Users\rubat\.venvs\nl-openapi-mcp
uv sync

# Linux / macOS
export UV_PROJECT_ENVIRONMENT="$HOME/.venvs/nl-openapi-mcp"
uv sync

3) Claude에 MCP 연결

Claude Code (.mcp.json):

claude mcp add nl --env NL_API_KEY=$NL_API_KEY -- uvx --from git+https://github.com/rubato103/nl-openapi-mcp nl-mcp

Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "nl-seoji": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/rubato103/nl-openapi-mcp", "nl-mcp"],
      "env": {
        "NL_API_KEY": "발급받은_API_KEY"
      }
    }
  }
}

4) MCP 도구 및 CLI 사용법

MCP 도구 목록

nl_status: API 키 설정 여부 및 OpenAPI 서버 상태 점검
nl_search: 일반/상세 키워드 검색 및 페이징 (title, author, publisher, keyword, isbn 등)
nl_detail: 제어번호 또는 표제를 통한 단건 상세 정보 조회
nl_collect: 대량 수집 및 로컬 파일(xlsx, csv, json, sqlite) 저장

CLI 예시

# 상태 점검
nl-mcp status

# 일반 검색
nl-mcp search --kwd "도서관" --rows 5

# 상세 검색
nl-mcp search --title "토지" --author "박경리"

# 대량 수집 후 엑셀 저장
nl-mcp collect --kwd "정보학" --max-records 50 --format xlsx --output results.xlsx

5) 공식 MCP 레지스트리 및 PyPI 등록

MCP Registry Identifier: io.github.rubato103/nl-openapi-mcp
PyPI Package: nl-openapi-mcp

nl openapi mcp