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）获取摘要和完整书目信息
• 多组采集 — 为每个组设置不同的搜索策略，并合并为一个语料库
• 导出 — xlsx · csv · json · sqlite
• 两种使用方式 — 在 Claude 中调用工具（MCP）· 在终端批量执行（CLI），共享同一核心

支持的票种：ARTI 论文 · REPORT 报告 · ATT 趋势 · RESEARCHER 研究者 · ORGAN 研究机构 （取决于账户订阅范围）

申请 API 密钥

1. 注册并登录 ScienceON
2. API Gateway → 申请认证密钥 → 审批后获取 认证密钥·Client ID
3. 在认证密钥管理中注册申请时使用的 MAC 地址，在 IP 管理中注册调用计算机的公网 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

手动配置 — 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 的 Agent 都可以直接连接 — 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	将多个搜索组的结果合并为一个语料库并采集

多组采集

有些语料库无法通过单个搜索词构建。可以将有区分度的词直接用于整体（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 약관·트래픽 정책을 따른다.