National Library of Korea Seoji OpenAPI search via REST API and local metadata harvesting
MCPpedia last refreshed this data
io.github.rubato103/nl-openapi-mcp is an MCP server that national Library of Korea Seoji OpenAPI search via REST API and local metadata harvesting. Its tool list has not been published yet over stdio and http, requires no API key, and scores 85/100 on MCPpedia's security, maintenance and efficiency rubric.
Config is the same across clients — only the file and path differ.
{
"mcpServers": {
"nl-seoji": {
"env": {
"NL_API_KEY": "발급받은_API_KEY"
},
"args": [
"--from",
"git+https://github.com/rubato103/nl-openapi-mcp",
"nl-mcp"
],
"command": "uvx"
}
}
}Are you the author?
Add this badge to your README to show your security score and help users find safe servers.
국립중앙도서관 대한민국 국가서지 OpenAPI (Seoji OpenAPI) 문헌·도서 서지 메타데이터 검색·수집 MCP 서버 + CLI. 자매 프로젝트 kci-openapi-mcp 및 scienceon-mcp와 동일한 공통 코어(REST/MCP/CLI/Exporter) 아키텍처를 공유합니다.
Run this in your terminal to verify the server starts. Then let us know if it worked — your result helps other developers.
uvx 'nl-openapi-mcp' 2>&1 | head -1 && echo "✓ Server started successfully"
After testing, let us know if it worked:
Five weighted categories — click any category to see the underlying evidence.
No known CVEs.
Checked nl-openapi-mcp against OSV.dev.
Click any tool to inspect its schema.
Be the first to review
Have you used this server?
Share your experience — it helps other developers decide.
Sign in to write a review.
Others in developer-tools
Context7 Platform -- Up-to-date code documentation for LLMs and AI code editors
Chrome DevTools for coding agents
Asynchronous coordination layer for AI coding agents: identities, inboxes, searchable threads, and advisory file leases over FastMCP + Git + SQLite
MCP server for using the GitLab API
MCP Security Weekly
Get CVE alerts and security updates for io.github.rubato103/nl-openapi-mcp and similar servers.
Start a conversation
Ask a question, share a tip, or report an issue.
Sign in to join the discussion.
📈 사용량 — 최근 14일 조회 24회(고유 7) · 클론 284회(고유 123) · 릴리스 자산 누적 다운로드 154
2026-08-24 자동 갱신 · 전체 이력은
docs/usage.csv. GitHub 트래픽 통계는 14일 창만 제공하므로 이 저장소가 매일 찍어 누적한다.
국립중앙도서관 소장자료 검색 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 을 함께 싣고, 상한에 걸리면 처방까지 문장으로 알려줍니다.
| 신호 | 뜻 | 처방 |
|---|---|---|
truncated | 이번 호출이 total 보다 적게 받음 | 대개 max_records 를 올리면 해결 |
cap_hit | total > 500 — API 가 더 안 줌 | max_records 로는 불가 (아래 참조) |
meta.cap_hit_terms | 상한에 걸린 검색어 목록 | 그 검색어만 세분화 |
교육복지/도서(1,856건) 라이브 실측:
| 설정 | 회수 | 비율 | 요청 |
|---|---|---|---|
| 우회 없음 | 500 | 27% | 1 |
sort_depth=3 | 1,746 | 94% | 7 |
auto_partition=True + sort_depth=1 | 1,854 | 100% | 24 |
sort_depth 가 비용 대비 효과가 압도적입니다 — 같은 검색식을 정렬 순서만 바꿔 다시 훑는데,
asc 와 desc 의 교집합이 0건이라 정렬축 하나가 상한을 사실상 2배로 늘립니다.
분할(auto_partition)과 직교하므로 함께 쓸 수 있습니다.
① auto_partition=True — 서버측 축으로 재귀 분할
응답 필드명을 파라미터로 넘겨보는 방식으로 실제 동작하는 축 3개를 찾았습니다:
category → manageName(둘 다 완전분할) → licYn. 상한에 걸린 조각만 다음 축으로 더 쪼개고,
부모 조각도 합집합에 넣어 불완전한 축을 써도 손해가 나지 않게 했습니다.
교육복지(전체 7,028건) 실측:
| 깊이 | 축 | 회수 | 비율 | 요청 |
|---|---|---|---|---|
| — | 분할 없음 | 500 | 7% | 1 |
| 1 | category | 2,134 | 30% | 13 |
| 2 | +manageName (기본) | 3,265 | 46% | 25 |
| 3 | +licYn | 4,722 | 67% | 60 |
partition_depth(1~3)로 조절합니다. ⚠️ 전수는 아니며 — 깊이 3에서도 33%가 남습니다 —
못 받은 건수는 meta.axes[].partition.unreachable 로 보고합니다.
② exact=True — 큰따옴표 구문검색 (⚠️ 넓게 모을 때는 쓰지 마세요)
total 자체가 줄어들어(교육불평등 63 → 28) 상한 아래로 내려갈 수 있습니다. 다만
재현율 손실이 큽니다 — 실측 평균 47%, 최악 84%(교육형평성 31 → 5건). 구문검색은 토큰
인접을 요구하는데 한국어 복합어는 표제에서 조사·수식어로 갈라지기 때문입니다
(교육의 형평성, 초중등교육의 형평성과). 버려진 것의 76%가 관련 문헌이었습니다.
→ 코퍼스 수집은 기본 검색 + contains 후처리, exact 는 전체 표제를 아는 특정 자료 조회용.
⚠️
year_from/contains는 이미 받은 레코드에 대한 후처리라 상한을 풀어주지 않습니다. 서버측 연도 범위 필터는 확인되지 않았습니다(11개 후보 무시).
🔴 정정(2026-08-12) — 이전 판에서 "정렬은 존재하지 않습니다"라고 적었으나 틀렸습니다.
sort=ipub_year&order=asc|desc가 동작합니다 →sort_depth로 구현했습니다(위 표).detailSearch=true+f1/v1/and1로 필드 간 AND/OR/NOT 도 됩니다(AND+NOT=부모검산 통과) — 이쪽은 아직 미구현입니다. 자세한 내용 → docs/NL_API_GUIDE.md §1-4-b·§1-6·§3-3
{
"mcpServers": {
"nl": {
"type": "stdio",
"command": "uvx",
"args": ["--from", "git+https://github.com/rubatoyd/nl-openapi-mcp", "nl-mcp"],
"env": { "NL_API_KEY": "발급받은_인증키" }
}
}
}
.mcpb 원클릭Releases 에서 내려받아 실행합니다.
Python·uv 가 없는 환경이면 OS별 자체완결 번들(-win-x64 / -macos-arm64 / -linux-x64)을 쓰세요.
git clone https://github.com/rubatoyd/nl-openapi-mcp
cd nl-openapi-mcp
uv sync
uv run pytest -q