Kci Openapi Mcp

io.github.rubatoydPublished by GitHub account rubatoydv0.3.6Updated Oct 24, 2026

KCI (Korea Citation Index) literature & citation search via REST Open API + OAI-PMH

VerifiedSTDIODesktop onlyKnowledge & MemoryData & Analytics

Overview

AI-generated overview

Searches and harvests Korea Citation Index (KCI) literature and citation data through the KCI REST Open API and OAI-PMH, with export to xlsx, csv, json or…

What you can do
  • Check connectivity and whether an API key is present
  • Search articles by title plus author, journal, keyword, DOI, date or institution filters, and fetch details by control number
  • Retrieve reference lists and build citation networks from KCI article IDs
  • Look up journal citation metrics such as yearly impact factors and listing history
  • Harvest records in bulk over OAI-PMH by set and date range, with a local keyword filter
  • Route requests automatically between REST and OAI and save results to files
When to use it
Useful for Korean-language bibliographic research: finding KCI-indexed papers, abstracts and authors, tracing references and citations, checking journal impact factors, or building a corpus of KCI records for analysis.
Requirements
Runs locally as a stdio MCP server, installed via a self-contained .mcpb bundle or through uv/uvx from the project repository. The REST tools need a KCI Open API key in the KCI_API_KEY environment variable, issued at open.kci.go.kr; OAI-PMH harvesting works without a key. Network access to KCI endpoints is required.
Before you install
The API key is passed as a plain query parameter and is stored in plain text in client config files, so keep it out of code and commits. HTTP transport modes have no authentication and expose a keyed server if bound beyond loopback. Harvesting and collection write files to disk, and KCI data use is subject to KCI's terms; the project is an unofficial client.

Installation

In SourceWeft

  1. Open Kci Openapi Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

kci-openapi-mcp

[CI] [Release] [Downloads]

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

[일별 클론·조회 추이]

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

한국연구재단(NRF) KCI(Korea Citation Index) 문헌·인용지수 검색·수집 MCP 서버 + CLI. REST Open API(키워드 검색)와 OAI-PMH(무인증 대량 수확)를 함께 다룬다.

기능

  • 논문 검색·상세 — 서지 · 국문/영문 초록 · 키워드 · 저자/소속
  • 참고문헌 수집 — 원형 텍스트 + 피인용 논문의 KCI ID(arti_id) → 인용 네트워크 구성
  • 저널 인용지수 — 연도별 IF · 등재이력
  • OAI-PMH 대량 수확 — 인증키 없이 세트 + 날짜범위 전수 수집
  • 내보내기 — xlsx · csv · json · sqlite

두 인터페이스

REST Open APIOAI-PMH
엔드포인트…/po/openapi/openApiSearch.kci…/oai/request
인증KCI_API_KEY 필요불필요
질의키워드 검색(title 필수)세트 + 날짜범위 수확
인용지수·참고문헌✅❌

규격: docs/KCI_API_GUIDE.md · docs/KCI_OAI_PMH_GUIDE.md · 설계: docs/ARCHITECTURE.md

인증키 없이 바로 써보기

REST 검색만 인증키가 필요하고, OAI-PMH 수확은 키 없이 동작한다.

bash
uvx --from git+https://github.com/rubatoyd/KCI_openAPI kci identify
bash
uvx --from git+https://github.com/rubatoyd/KCI_openAPI kci harvest --set ARTI --from 2024-01-01 --until 2024-03-31 --contains 학부모 --max 200

MCP 로 붙였다면 kci_status → kci_harvest 순으로 바로 쓸 수 있다. 키가 없으면 REST 도구는 오류 대신 OAI 대안을 안내한다.

인증키 발급

REST 도구(kci_search · kci_detail · kci_references · kci_journal_citation)에만 필요하다.

  1. open.kci.go.kr 에서 Open API 이용 신청
  2. 발급된 인증키 문자열 1개를 받는다
  3. 아래 중 한 곳에 넣는다 — 코드나 커밋에는 넣지 않는다
사용 환경넣는 곳
Claude Code.claude/settings.local.json 의 env (gitignore 대상)
Claude Desktopclaude_desktop_config.json 의 env — 평문 인라인(${VAR} 확장 안 됨)
.mcpb 설치설치 창의 입력란
CLI / 로컬 개발.env(gitignore) 또는 OS 사용자 환경변수

AES 암호화·토큰 발급·공인 IP 등록은 불필요하다. 평문 key 쿼리 파라미터 하나로 호출한다.

설치

Claude Desktop

자체완결 .mcpb(권장) — Python·uv 불필요. 릴리스에서 OS에 맞는 파일을 받아 더블클릭(또는 Settings → Extensions → Install) → KCI_API_KEY 입력(선택).

자산특징
kci-openapi-mcp-win-x64.mcpb / …-macos-arm64.mcpb / …-linux-x64.mcpb자체완결 — 사전 설치물 없음
kci-openapi-mcp.mcpb경량. 실행에 uv 필요

수동 config — %APPDATA%/Claude/claude_desktop_config.json:

json
{ "mcpServers": { "kci": {  "command": "uvx",  "args": ["--from", "git+https://github.com/rubatoyd/KCI_openAPI", "kci-mcp"],  "env": { "KCI_API_KEY": "<발급키 또는 비움>", "KCI_OS_TRUST": "1" }} } }

Claude Code

bash
claude mcp add kci --env KCI_API_KEY=$KCI_API_KEY -- uvx --from git+https://github.com/rubatoyd/KCI_openAPI kci-mcp

프로젝트 루트의 .mcp.json 도 자동 인식된다.

다른 MCP 클라이언트

표준 stdio MCP 서버이므로 MCP 를 지원하는 에이전트면 그대로 붙는다 — Cursor · Windsurf · Cline · Zed · VS Code Copilot(agent mode) · OpenAI Agents SDK · 자체 클라이언트 등. 위 command/args/env 3요소를 각 클라이언트 설정에 옮기면 된다.

python
from mcp import StdioServerParameters
params = StdioServerParameters(    command="uvx",    args=["--from", "git+https://github.com/rubatoyd/KCI_openAPI", "kci-mcp"],    env={"KCI_API_KEY": "..."},   # 비우면 OAI 무인증 도구만)

전송 방식

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

환경변수: KCI_MCP_TRANSPORT · KCI_MCP_HOST · KCI_MCP_PORT.

MCP 도구

도구하는 일
kci_status연결 점검 — OAI Identify + 인증키 보유 여부
kci_search논문 검색 — title 필수 + author/journal/keyword/abstract/doi/발행연월/institution 필터, 정렬
kci_detailControl Number(ART…)로 상세 — 키워드·ISSN·저자소속·참고문헌의 유일한 출처
kci_references제목 검색어에 매칭된 논문들의 참고문헌 원형
kci_journal_citation저널 인용지수 — 연도 목록 / journal_id 상세(등재이력·연도별 IF)
kci_harvestOAI-PMH 무인증 대량 수확 — 세트 + 날짜범위, contains 로컬 필터
kci_collect라우터 — 키 유무·요청 성격으로 REST↔OAI 자동 선택 후 파일 저장

알아둘 제한

articleSearch 는 키워드·ISSN·UCI 를 응답에 싣지 않는다. keyword= 로 검색은 되지만 결과에는 없다. 검색 결과의 빈 keywords 는 '키워드 없는 논문'이 아니다 — 필요하면 kci_detail 로 건별 보강한다.

kci_collect 의 REST 경로는 제목축 ∪ 키워드축이다. 각 검색어를 두 축으로 조회해 합집합을 만든다. 결과는 '제목검색 결과'가 아니므로 코퍼스 경계를 기술할 때 명시해야 한다. meta.axes 에 축별 total 이 담긴다.

참고문헌의 arti_id 는 KCI 등재분에만 붙는다. 단행본·보고서·해외문헌은 빈 문자열이다. 인용 네트워크는 이 ID 가 있는 항목으로만 구성할 수 있다(references_linked_count 로 확인).

referenceSearch 는 페이지 파라미터가 없어 1회 100건이 상한이다. 부족한 이유가 둘이고 처방이 정반대이므로 경고 문구를 확인해야 한다.

상황처방
total > 100 — API 가 더 줄 수 없다sort_dir 를 뒤집어(asc↔desc) 반대쪽을 받아 합집합
total ≤ 100 인데 rows 로 잘렸다rows 를 total 이상으로 올린다 (정렬 반전은 같은 레코드만 다시 온다)

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

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

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

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

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

정렬 인자는 전송 전에 검증한다. sort_by 는 title/author/pubiYr, sort_dir 은 asc/desc. 허용값 밖이면 오류를 돌려준다.

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

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

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

CLI

bash
kci identify                                  # OAI 무인증 — 키 없이 즉시kci harvest --set ARTI --from 2024-01-01 --until 2024-12-31 --contains 학부모 --max 500kci search --title 경계선지능 --rows 20        # REST(인증키 필요)kci collect --config config/borderline_slow.yaml

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

네트워크

  • KCI 방화벽은 User-Agent 필터를 건다. curl 기본 UA 는 차단 안내페이지를 받는다. 본 서버는 requests 로 호출하므로 정상 동작한다.
  • 교육망·사내망 SSL 인터셉션 환경에서는 truststore 로 OS 신뢰저장소를 사용해 통과한다 (TLS 검증을 끄지 않는다). 비활성은 KCI_OS_TRUST=0.
  • HTTP 전송에는 인증이 없다. 기본 바인드는 루프백(127.0.0.1)이다. --host 0.0.0.0 으로 외부에 열면 인증키를 가진 서버가 그대로 노출되므로 신뢰된 망에서만 쓴다.

라이선스

MIT. 본 프로젝트는 한국연구재단의 비공식 클라이언트이며 제휴 관계가 없다. KCI 데이터 이용은 KCI 약관을 따른다.

Source: README.md at commit 8251f71

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.3.6LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts