Nl Openapi MCP server

nl-openapi-mcp

<!-- mcp-name: io.github.rubatoyd/nl-openapi-mcp -->

<!-- usage:start -->

📈 사용량 — 최근 14일 조회 0회(고유 0) · 클론 0회(고유 0) · 릴리스 자산 누적 다운로드 —

2026-09-24 자동 갱신 · 전체 이력은 docs/usage.csv. GitHub 트래픽 통계는 14일 창만 제공하므로 이 저장소가 매일 찍어 누적한다.

<!-- usage:end -->

국립중앙도서관 소장자료 검색 OpenAPI 를 Claude 등 MCP 클라이언트에서 바로 쓰는 서버 + CLI. 단행본·온라인자료의 서지, KDC 분류, 청구기호, 원문 제공 여부를 검색·수집하고 xlsx/csv/json/sqlite 로 내보냅니다.

자매 프로젝트: kci-openapi-mcp(학술논문·인용지수) · scienceON-mcp(KISTI 문헌)

이 도구가 특별히 신경 쓰는 것 — 조용한 절단 방지

국립중앙도서관 검색 API 는 한 검색식당 500건까지만 돌려줍니다(공식 오류코드 012 DATA LIMIT 500). 그런데 total 은 그보다 큰 값을 태연히 보고합니다.

교육복지: total=1,856  →  실제로 받을 수 있는 건 500건

이 사실을 모르면 부분 집합을 전수로 오인하게 됩니다. 그래서 모든 응답에 total·truncated·cap_hit 을 함께 싣고, 상한에 걸리면 처방까지 문장으로 알려줍니다.

상한을 넘겨 모으는 방법 — 함께 쓰면 전수 수집이 됩니다

교육복지/도서(1,856건) 라이브 실측:

sortdepth 가 비용 대비 효과가 압도적입니다 — 같은 검색식을 정렬 순서만 바꿔 다시 훑는데, asc 와 desc 의 교집합이 0건이라 정렬축 하나가 상한을 사실상 2배로 늘립니다. 분할(autopartition)과 직교하므로 함께 쓸 수 있습니다.

① autopartition=True — 서버측 축으로 재귀 분할**

응답 필드명을 파라미터로 넘겨보는 방식으로 실제 동작하는 축 3개를 찾았습니다: category → manageName(둘 다 완전분할) → licYn. 상한에 걸린 조각만 다음 축으로 더 쪼개고, 부모 조각도 합집합에 넣어 불완전한 축을 써도 손해가 나지 않게 했습니다.

교육복지(전체 7,028건) 실측:

partition_depth(1~3)로 조절합니다. ⚠️ 전수는 아니며 — 깊이 3에서도 33%가 남습니다 — 못 받은 건수는 meta.axes[].partition.unreachable 로 보고합니다.

② exact=True — 큰따옴표 구문검색 (⚠️ 넓게 모을 때는 쓰지 마세요)

total 자체가 줄어들어(교육불평등 63 → 28) 상한 아래로 내려갈 수 있습니다. 다만 재현율 손실이 큽니다 — 실측 평균 47%, 최악 84%(교육형평성 31 → 5건). 구문검색은 토큰 인접을 요구하는데 한국어 복합어는 표제에서 조사·수식어로 갈라지기 때문입니다 (교육의 형평성, 초중등교육의 형평성과). 버려진 것의 76%가 관련 문헌이었습니다.

→ 코퍼스 수집은 기본 검색 + contains 후처리, exact 는 전체 표제를 아는 특정 자료 조회용.

⚠️ yearfrom/contains 는 이미 받은 레코드에 대한 후처리**라 상한을 풀어주지 않습니다.

서버측 연도 범위 필터는 확인되지 않았습니다(11개 후보 무시).

🔴 정정(2026-08-12) — 이전 판에서 "정렬은 존재하지 않습니다"라고 적었으나 틀렸습니다.

sort=ipubyear&order=asc|desc 가 동작합니다 → sortdepth 로 구현했습니다(위 표).

detailSearch=true+f1/v1/and1 로 필드 간 AND/OR/NOT 도 됩니다(AND+NOT=부모 검산 통과) —

이쪽은 아직 미구현입니다. 자세한 내용 → docs/NLAPIGUIDE.md §1-4-b·§1-6·§3-3

설치

1) Claude Code / Claude Desktop (uvx — 권장)

{
  "mcpServers": {
    "nl": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "git+https://github.com/rubatoyd/nl-openapi-mcp", "nl-mcp"],
      "env": { "NL_API_KEY": "발급받은_인증키" }
    }
  }
}

2) Claude Desktop .mcpb 원클릭

Releases 에서 내려받아 실행합니다. Python·uv 가 없는 환경이면 OS별 자체완결 번들(-win-x64 / -macos-arm64 / -linux-x64)을 쓰세요.

3) 로컬 개발

git clone https://github.com/rubatoyd/nl-openapi-mcp
cd nl-openapi-mcp
uv sync
uv run pytest -q

Shortened. The full README is on GitHub.