Na Openapi MCP server

na-openapi-mcp

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

<!-- usage:start -->

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

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

<!-- usage:end -->

국회도서관(National Assembly Library of Korea) 자료검색 OpenAPI 를 Claude 등 MCP 클라이언트에서 바로 쓰는 서버 + CLI. 도서·학위논문·국내외 기사·국회회의록·의안정보 등 21종 DB 를 검색·수집하고 xlsx/csv/json/sqlite 로 내보냅니다.

자매 프로젝트: nl-openapi-mcp(국립중앙도서관 단행본·회색문헌) · kci-openapi-mcp(학술논문·인용지수) · scienceON-mcp(KISTI 문헌)

이 도구가 특별히 신경 쓰는 것

① 미지원 검색항목이 오류 대신 전체 카탈로그를 돌려줍니다

이 API 최대의 함정입니다. 통합검색은 검색항목 이름을 모르면 거부하지 않고 검색어를 통째로 무시합니다.

저자,오욱환      →  total=76          ← 정상
저자명,오욱환    →  total=13,097,591  ← 전체 DB. 오류도 경고도 없다

저자명 은 상세검색에서는 유효한 이름이라 오타가 아니라 헷갈려서 쓰기 쉽습니다. 그대로 두면 1,300만 건을 '검색 결과'로 오인하게 됩니다. → 이 서버는 화이트리스트로 호출 전에 거부하고 올바른 이름을 알려줍니다.

② 조용한 절단 방지

받은 것이 전부인지, 잘린 것인지를 항상 메타로 알려줍니다.

회수 한계는 pageno 최대 99 × pagesize 입니다(실측). 기본값(1000)이면 99,000건이고, pagesize 를 낮추면 한계도 함께 낮아집니다 — 이 서버는 그것까지 반영해 보고합니다.

③ 공식 문서와 실제가 다른 곳을 실측으로 확정했습니다

문서(.hwp/.docx)만 보고 만들면 조용히 깨지는 지점들입니다.

전체 대조표와 근거는 docs/NAAPIGUIDE.md 에 있습니다.

설치

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

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

2) Claude Desktop .mcpb 원클릭

릴리스에서 내려받아 실행합니다. 경량본(na-openapi-mcp.mcpb, uvx 경유)과 Python·uv 없이 도는 자체완결본 (win-x64 · macos-arm64 · linux-x64)이 있습니다.

3) 로컬 개발

git clone https://github.com/rubatoyd/na-openapi-mcp
cd na-openapi-mcp
uv sync --all-groups
uv run pytest -q
uv run na status

4) 다른 MCP 클라이언트

stdio 전송이 기본입니다. HTTP 가 필요하면 na-mcp --transport streamable-http --host 127.0.0.1 --port 9126 (환경변수 NAMCPTRANSPORT·NAMCPHOST·NAMCPPORT 도 지원).

인증키

Shortened. The full README is on GitHub.