na-openapi-mcp

na-openapi-mcp

📈 使用状況 — 直近14日間の閲覧 1回（ユニーク1） · クローン 157回（ユニーク97） · リリースアセットの累計ダウンロード 94

_{2026-10-27 自動更新 · 全履歴は docs/usage.csv。GitHub のトラフィック統計は14日間のデータしか提供されないため、このリポジトリが毎日記録して累積しています。}

国会図書館（National Assembly Library of Korea）の資料検索 OpenAPI を Claude などの MCP クライアントからそのまま使えるサーバー＋CLI です。図書・学位論文・国内外の記事・国会会議録・議案情報など 21種のデータベースを検索・収集し、xlsx/csv/json/sqlite にエクスポートします。

姉妹プロジェクト：nl-openapi-mcp（国立中央図書館の単行本・灰色文献） · kci-openapi-mcp（学術論文・引用指数） · scienceON-mcp（KISTI 文献）

---

このツールが特に重視すること

① 未対応の検索項目でエラーではなく全カタログが返る

この API 最大の落とし穴です。統合検索では、検索項目名が認識されなくても拒否せず、検索語を 丸ごと無視します。

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

저자명 は詳細検索では有効な名前なので、誤字ではなく紛らわしくて使いがちです。 そのままにすると、1,300万件を「検索結果」と誤認することになります。 → このサーバーはホワイトリストにより、呼び出し前に拒否して正しい名前を知らせます。

検索項目	오욱환 の検索結果
전체 · 기본검색 · 자료명 · 저자 · 키워드	105 · 88 · 4 · 76 · 7
저자명 · ISBN · 발행년도 · 誤字	各13,097,591（全データベース）

② 気付かないまま結果が切り捨てられるのを防止

取得したデータがすべてなのか、途中で切れたのかを常にメタデータで知らせます。

シグナル	意味	対処法
truncated	max_records で停止	値を上げれば解決
cap_hit	total > 取得上限 — API がこれ以上返さない	検索式を分割する必要があります
early_stop_note	新規レコードが0件になり早期終了	重複応答・サーバー異常の可能性
stopped_early_note	予算切れにより照会すらできなかった検索語	max_records を上げる
zero_yield_warning	受け付けられるが常に0件になる検索項目	別の項目を使用
option_ignored_warning	年フィルターが無視された（統合検索）	dbname を併せて指定
ignored_search_warning	全カタログの規模に相当する結果が返された	検索項目を確認
toc_enrich_truncated_note	目次候補のうち一部のみ補完	toc_max を上げる
toc_enrich_incomplete_note	目次の照会に失敗した項目がある	上限を上げても無意味 — 制御番号を確認
toc_enrich_aborted_note	クォータ・キーの問題で補完を中断	上限を上げると悪化 — na_status

取得上限は pageno 最大 99 × page_size です（実測）。デフォルト値（1000）では99,000件で、 page_size を下げると上限も下がります — このサーバーはその点も反映して報告します。

③ 公式ドキュメントと実際の違いを実測で確認しました

ドキュメント（.hwp/.docx）だけを見て作ると、気付かないまま壊れる箇所です。

項目	公式ドキュメント	✅ 実際
レコードタグ	<record>	<recode> — ドキュメントどおりだと全件取得数0件なのに total は正常
<item> の子要素の順序	value → name	name → value
制御番号のフィールド名	controlno	제어번호
displaylines の上限	100	1000
認証キー	（記載なし）	Encoding 値を URL に直接結合する必要があります
ハイライトのマークアップ	（記載なし）	マッチしたフィールドに <font color="red"> を挿入

全項目の比較表と根拠は docs/NA_API_GUIDE.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 （環境変数 NA_MCP_TRANSPORT·NA_MCP_HOST·NA_MCP_PORT にも対応）。

---

認証キー

公共データポータル data.go.kr で国会 国会図書館_資料検索サービス （データセット 15098174）の利用申請後、発行を受けます。開発アカウントのトラフィックは1日10,000件です。

na_detail·na_toc を使うには、詳細情報照会サービス（15098175）も併せて申請してください — 認証キーはアカウント単位なので、同じキーをそのまま使えます。

NA_API_KEY=발급받은_키          # Decoding(원문) 권장
NA_API_KEY_ENCODED=            # Encoding 값만 있으면 이쪽에
NA_OS_TRUST=1                  # 교육망·사내망 SSL 인터셉션 대응(기본 1)

🔑 data.go.kr は認証キーをEncoding / Decoding の2種類提供します。この API ではEncoding 値を URL に直接結合する必要があります（実測）。ライブラリの params= に渡すと %2B が %252B に二重エンコードされ、気付かないまま認証に失敗します。どちらを入力してもコードが自動で 変換するため、気にする必要はありません。

---

MCP ツール

ツール	役割
na_status	認証キーの有無＋実際の往復通信を1回実行
na_search	資料検索。切り捨てシグナルも返します
na_collect	検索語の和集合を収集 → xlsx/csv/json/sqlite。toc_max で目次本文を補完（デフォルトでは無効）
na_detail	制御番号1件の詳細情報
na_toc	制御番号1件の目次
na_fields	検索項目・dbname の有効値＋実測根拠（census）

検索語の形式

検索項目,キーワード です。| でつなぐと AND でまとめられます。

전체,교육불평등
전체,교육|자료명,불평등          ← AND

OR（和集合）は API に構文がないため、na_collect(terms=[…]) が作成します。

統合検索の検索項目（7種）：基本検索 全体 資料名 著者 発行者 キーワード 請求記号

dbname を指定すると詳細検索に切り替わり、検索項目の語彙は DB ごとに異なります （学位論文＝論文名・指導教授、国内記事＝記事名、学術誌・新聞＝収録誌名/新聞名で1つの項目）。 正確な一覧は na_fields で確認してください。

---

CLI

na status
na fields                          # 검색항목·dbname 유효값 (--json 으로 census 전체)
na search "전체,교육불평등" --max-records 20
na search "저자명,양연동" --dbname 학위논문
na collect --terms "전체,교육불평등" "전체,교육격차" --max-records 2000

# 목차 본문까지 붙이기 — 건당 1회를 더 씁니다(기본 꺼져 있음). 본문은 json·sqlite 에만.
na collect --search "자료명,교육불평등" --dbname 일반도서 --toc-max 300 --formats json xlsx
na detail MONO12026000012887
na toc    MONO12026000012887

# 연도 범위는 상세검색의 option 으로만 걸립니다(통합검색에서는 무시됨)
na search "자료명,교육" --dbname 일반도서 --option "발행년도,2000|발행년도,2010"

---

応答フィールド

レコードは固定スキーマではありません。 <item><name>・<value> のペアで、名前の集合は 資料種ごとに異なります — 表題フィールドだけでも 資料名（図書）／論文名（学位論文）／ 記事名（記事）／収録誌名/新聞名（学術誌・新聞）／ジャーナル名（電子ジャーナル）／案件（会議録）／ 議案名（議案情報）／翻訳法令名／表図名 に分かれます。

既知の名前は共通カラムに正規化し、元データは raw にそのまま保存します。

注意が必要な値（すべて実測）：

• 案内文が値として入ることがあります — E-BOOK の DDC は99.95%が 電子形態でのみ閲覧可能 です。正規化フィールドは空にして、placeholder_fields に名前を残します（原文は raw に保存します）。
• 年が4桁とは限りません — 201u（MARCの不確定年）、空値、0。
• 초록유무=Y でも抄録本文を取得する方法はありません。 記述テキストがあるのは 国会議案情報（提案理由および主要内容）・国会会議録（内容）のみです。
• 全件に目次がない資料種：E-BOOK・学術誌、雑誌・新聞・国外記事・動画資料。

目次の補完（toc_max）を有効にした場合

目次が付かない理由は5つあり、それぞれ対処法が異なります。 同じ空欄として混在させると「この資料には 目次がない」という誤った結論につながるため、toc_status カラムで行ごとに理由を区別します。

toc_status	意味	対処法
ok	本文を取得済み	—
skipped	目次 フラグが Y ではない、または制御番号がない — 呼び出しません	—（クォータを消費しません）
empty	正常な応答ですが本文がありません → フラグが誤っていました	—
sentinel	本文が 目次情報なし の繰り返し	—
failed	取得に失敗	na_toc で個別に再取得
not_attempted	予算切れ・中断により呼び出せませんでした	toc_max を引き上げる

has_toc='Y' なのに toc_status='empty' の行は最も重要なシグナルであるため、2つのカラムを並べています。 本文（toc_text）は json・sqlite にのみ含まれます — 数千文字になるため xlsx のセル上限（32,767）に達し、 csv のサイズも大きくなるためです。

---

検証状況

• 回帰テスト209件。 パーサー・収集器だけでなく、計測ツール自体も固定しています （tests/test_probe_instrumentation.py）— ホワイトリストはプローブの出力であり、プローブが気づかれないまま 誤ると、その誤りがそのままコードになるためです。CI ではテストに加え、クライアントが実際に起動できるかを 確認します — 新しい依存関係を解決する際の mcp.server.fastmcp の存在確認、実際の stdio ハンドシェイク、 6種類のツールの公開、キーなしでの CLI 起動、秘密ファイルが追跡対象になっていないこと。
• API の事実はすべてライブの往復通信で確認しました（ドキュメントや姉妹プロジェクトから転記していません）。 13種類の資料のフィールド census のサンプルは約21,000件です。再現方法：scripts/probe_*.py。
• 詳細な根拠と検証レベル（✅ 実測／📄 ドキュメント根拠／❓ 未検証）は docs/NA_API_GUIDE.md にあります。

---

ライセンス

MIT