scienceon-mcp

scienceON-mcp

📈 利用状況 — 過去14日間の閲覧 0 回（ユニーク0） · クローン 0 回（ユニーク0） · リリースアセットの累計ダウンロード —

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

KISTI ScienceON OpenAPI の文献検索・メタデータ収集ツール — MCP サーバー + CLI。 ScienceON API キーを取得するだけで、Claude（または CLI）から国内外の論文・レポートの書誌メタデータを 検索・収集できます。

KISTI ScienceON OpenAPI 用の MCP サーバー + CLI です。ご自身の API キーを用意すれば、 Claude があらゆるプロジェクトで学術文献のメタデータを検索・収集できます。

機能

• 検索 — 論文（ARTI）・レポート（REPORT）などの書誌メタデータ。複数クエリの和集合 · ワイルドカード（*） · 年範囲 · contains/lang による後処理フィルター
• 詳細 — 制御番号（CN）による概要・書誌情報全体
• 複数グループ収集 — グループごとに異なる検索戦略を適用し、1つのコーパスに統合
• エクスポート — xlsx · csv · json · sqlite
• 2つの使い方 — Claude からツールを呼び出す（MCP）· ターミナルでバッチ処理する（CLI）。同じコアを共有

対応チケット：ARTI 論文 · REPORT レポート · ATT 動向 · RESEARCHER 研究者 · ORGAN 研究機関 （アカウントの契約範囲によります）

API キーの取得

1. ScienceON に登録・ログイン
2. API Gateway → 認証キーの発行申請 → 承認後に 認証キー・Client ID が発行されます
3. 認証キー管理で申請時の MAC アドレスを登録し、IP 管理で呼び出し元 PC のグローバル IP を登録
4. 使用する **サービスコンテンツ（チケット）**にチェックを入れる

認証情報は、MCP 設定の env ブロックまたは .env（.env.example をコピー）で渡します。コード・コミット・ログには 含めないでください。

インストール

Claude Desktop

.mcpb ワンクリック — リリースからダウンロードして ダブルクリック／ドラッグ → インストール画面で認証キー・Client ID・MAC を入力します。

アセット	特徴
scienceon-mcp-win-x64.mcpb / …-macos-arm64.mcpb / …-linux-x64.mcpb	単体で完結 — Python・uv は不要
scienceon-mcp.mcpb	軽量版。実行には uv が必要

手動 config — claude_desktop_config.json:

{
  "mcpServers": {
    "scienceon": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/rubatoyd/scienceON-mcp", "scienceon-mcp"],
      "env": {
        "SCIENCEON_AUTH_KEY": "발급_32자리_인증키",
        "SCIENCEON_CLIENT_ID": "발급_client_id",
        "SCIENCEON_MAC_ADDRESS": "AA-BB-CC-DD-EE-FF"
      }
    }
  }
}

Claude Code

claude mcp add scienceon -- uvx --from "git+https://github.com/rubatoyd/scienceON-mcp" scienceon-mcp

初回実行時にビルドします（数秒）。以降はキャッシュされます。最新の内容を反映するには uvx --refresh … を実行します。

その他の MCP クライアント

標準の stdio MCP サーバーなので、MCP に対応するエージェントであればそのまま接続できます — Cursor · Windsurf · Cline · Zed · VS Code Copilot（agent mode）· OpenAI Agents SDK · 独自クライアントなど。上記の command/args/env の3要素を各クライアントの設定に移してください。

トランスポート方式

scienceon-mcp                                # stdio (기본)
scienceon-mcp --transport streamable-http    # http://127.0.0.1:8000/mcp
scienceon-mcp --transport sse --port 9000    # http://127.0.0.1:9000/sse

環境変数：SCIENCEON_MCP_TRANSPORT · SCIENCEON_MCP_HOST · SCIENCEON_MCP_PORT。

MCP ツール

ツール	機能
scienceON_status	接続／トークンを確認（+グローバル IP — E4006 の診断用）
scienceON_search	文献検索 — 複数クエリ · ワイルドカード · 年範囲 · contains · lang
scienceON_detail	制御番号（CN）による概要・書誌情報全体
scienceON_export	大量収集 → xlsx/csv/json/sqlite に保存
scienceON_collect_groups	複数の検索グループを1つのコーパスに統合して収集

複数グループ収集

単一の検索語では作れないコーパスがあります。識別力のある単語は全体（BI）でそのまま検索し、 インデックス化されないトークンはタイトル（TI）のワイルドカードと contains による後処理で絞り込むなど、グループごとに異なる 戦略を適用して和集合を作ります。

[
  { "field": "BI", "terms": ["경계선지능", "경계선 지능"] },
  { "field": "TI", "terms": ["느린*"], "contains": ["느린학습자", "느린 학습자"] }
]

グループキー：field（BI/TI/AB/AU/KW）· terms · contains · lang · max。 save: false を指定すると、保存せずに結果をプレビューできます（応答には先頭100件のみ含まれます）。

알아둘 제한

수집량이 max_records 와 정확히 일치하면 거의 항상 절단된 것이다. 수집 도구는 total 과 플래그를 함께 반환하므로 절단 여부를 확인할 수 있다. 절단된 결과를 완전한 코퍼스로 오인하면 후속 분석이 통째로 무효가 된다.

ScienceON 이 보고하는 total 은 실제로 받을 수 있는 건수보다 클 수 있다. 그래서 두 상황을 다른 플래그로 구분한다.

플래그	뜻	대처
truncated	max_records 상한에 걸렸다	상한을 올려 재수집하면 늘어난다
total_mismatch	끝까지 페이징했는데 total 에 못 미쳤다	상한을 올려도 늘지 않는다. 회수량을 확정 수치로 쓴다

meta.union_upper_bound 는 실행한 검색축들의 total 합, 즉 합집합의 상한이다(중복 미보정).

다중 페이지 질의는 호출마다 결과가 미세하게 달라진다. 단일 페이지 질의는 안정적이다. total 에 못 미치고 상한도 아니면 한 번 더 훑어 합집합을 취한다(meta.sweeps 가 1보다 크면 보정된 것).

보정이 걸린 축은 전체를 재페이징하므로 그만큼 요청이 늘어난다. 대규모 수집에서 부담되면 scienceON_search · scienceON_export · scienceON_collect_groups 의 retry_incomplete=0 으로 끈다 — 대신 결손이 남고 total_mismatch 로만 표시된다.

출력 파일명은 정규화된다. name 을 지정하지 않으면 검색어가 그대로 파일명이 되므로, 경로 구분자·..·윈도 금지문자는 제거되고 결과는 항상 out_dir 안에만 저장된다. 한글 파일명은 그대로 보존된다.

서버측 파이프 OR(|)는 쓰지 않는다. 공백이 든 용어에서 토큰이 분리돼 과대매칭되므로, 용어별 개별 검색 후 CN 합집합을 취한다.

Claude 앱 안에서 검색해 설치할 수는 없다. 공식 MCP 레지스트리 등재와 Claude Desktop 인앱 커넥터 디렉터리는 별개이고 자동 동기화되지 않는다.

도구 설명이 한국어다. 한국어를 다루는 모델이어야 도구 선택이 정확하다.

mcp SDK 는 1.x 로 고정된다(mcp>=1.2.0,<2). 2.0 에서 mcp.server.fastmcp 가 제거되어 상한이 없으면 기동에 실패한다.

CLI

uv run scienceon status
uv run scienceon search --target ARTI --query "인공지능" --year 2015~2024 --rows 100
uv run scienceon collect --config config/search.example.yaml

로컬 개발은 clone 후 uv sync. 클라우드 동기화 폴더(OneDrive 등)라면 venv 를 폴더 밖에 두기를 권한다(UV_PROJECT_ENVIRONMENT).

문서

• docs/SCIENCEON_API_GUIDE.md — API 호출 규격
• docs/COLLECTION_WORKFLOW.md — 반복 수집 SOP
• docs/PROMPTS.md — Claude 구동용 프롬프트 템플릿
• docs/ROADMAP.md — 기능 구현 계획

보안 / 네트워크

• 자격증명은 .env 또는 MCP env 블록으로만 전달한다. .env 와 토큰 캐시는 gitignore 대상이다.
• 교육망·사내망 SSL 인터셉션 환경에서는 truststore 로 OS 신뢰저장소를 사용해 통과한다 (TLS 검증을 끄지 않는다). 정식 의존성이라 .mcpb 설치본에도 적용된다. 비활성은 SCIENCEON_OS_TRUST=0.
• 자격증명 오류·타임아웃 등 어떤 예외도 도구 밖으로 새지 않는다(항상 {"error": …} 형태로 반환).
• HTTP 전송에는 인증이 없다. 기본 바인드는 루프백(127.0.0.1)이다. --host 0.0.0.0 으로 외부에 열면 자격증명을 가진 서버가 그대로 노출되므로 신뢰된 망에서만 쓴다.
• 호출은 throttle(기본 0.5s)·지수 백오프를 건다. 429 가 나면 throttle 을 올린다.

관련 프로젝트

• ansua79/scienceon-mcp — KISTI 개발자의 ScienceON MCP. ScienceON 전 API(논문·특허·보고서·동향·연구자·기관·기술트렌드·뉴스 등 17개 도구)를 폭넓게 노출하고 GUI 설치기도 제공한다. 폭넓은 탐색이 목적이면 이 도구를 권한다.
• rubatoyd/KCI_openAPI — 한국연구재단 KCI 수집기(자매 프로젝트).

본 프로젝트는 연구용 자료수집·코퍼스 구축에 특화되어 있다 — 다중쿼리 합집합 · 와일드카드 · 후처리 필터 · 다중그룹 수집 · 대량 내보내기 · config 재현 수집.

라이선스

MIT © Yeondong Yang. 본 프로젝트는 KISTI 의 비공식 클라이언트이며 제휴 관계가 없다. ScienceON 데이터 이용은 KISTI 약관·트래픽 정책을 따른다.