Zotero MCP Server: Zotero를 열 필요 없이 10,000편의 PDF를 약 20 ms에 검색

Q: MCP 서버가 동작하려면 Zotero를 계속 실행해 두어야 하나요?

아니요 —— 검색과 읽기에는 필요하지 않습니다. 코어는 Zotero 데이터 디렉터리(zotero.sqlite와 storage/)를 직접 읽으므로 Zotero가 닫혀 있어도, 심지어 그 머신에서 Zotero 데스크톱 앱이 실행되고 있지 않아도 인덱싱과 검색이 동작합니다. Zotero 로컬 API를 거치는 것은 세 가지 쓰기 도구(항목 가져오기, 노트 추가, 태그·컬렉션 일괄 편집)뿐이므로, 그것들에는 Zotero가 열려 있어야 합니다.

Q: Zotero MCP 서버는 JavaScript뿐 아니라 Python도 지원하나요?

네. 기능이 동등한 두 개의 셸이 있습니다. JavaScript/Node 사용자를 위한 npm의 @docsagent/mcp-zotero와 Python 3.10+를 위한 PyPI의 docsagent-mcp-zotero입니다. 둘 다 동일한 스키마, 에러 코드, 쓰기 게이트로 같은 8개 도구를 노출하며, 동일한 번들 C++ 코어를 관리합니다.

Q: AI 에이전트가 내 Zotero 라이브러리를 수정할 수 있나요?

당신이 허용한 경우에만 가능합니다. enableWrites가 true로 설정되지 않으면 쓰기 도구는 등록되지 않고, 확인되지 않은 호출은 미리보기를 반환하며, 확인된 쓰기는 속도 제한(기본 30/hour)을 받고, 20개를 넘는 다중 항목 배치는 명시적 확인을 요구합니다.

1세대 Zotero MCP server를 써 본 적이 있다면 그 의식을 기억할 것입니다. Zotero를 열어 두고, 로컬 API를 활성화하고, 쿼리마다 라이브러리를 메타데이터 한 건씩 기어가며 훑어야 했습니다. 데모용으로는 충분합니다. 하지만 라이브러리에 5,000편의 PDF가 있고, 당신이 문장 하나를 다 입력하기도 전에 에이전트가 스무 번의 검색을 쏟아낸다면 전혀 충분하지 않습니다.

새로운 Zotero MCP Server —— @docsagent/mcp-zotero v4.0.1, 2026년 9월 21일 릴리스 —— 는 전혀 다른 기계입니다. 상주하는 네이티브 C++ 검색 코어 위에 **두 개의 셸(JavaScript와 Python)**을 얹고 Zotero 데이터 디렉터리를 직접 읽습니다. Zotero를 열지 않고도 검색이 동작하며, 10,000편 이상의 PDF를 가진 라이브러리가 Claude Code, Cursor, Codex, Claude Desktop, Gemini CLI, Qwen Code, Cline 또는 다른 어떤 MCP 클라이언트에게도 밀리초 단위의 지식 기반이 됩니다.

이 글은 새 버전 가이드입니다. 무엇이 바뀌었는지, 두 런타임에 각각 어떻게 설치하는지, 에이전트가 사용할 수 있는 8개 도구, 그리고 진짜 대형 라이브러리의 벤치마크 수치를 다룹니다.

Zotero MCP Server 4.0의 새로운 점

두 개의 셸, 하나의 코어. 동일한 도구 계약이 npm의 TypeScript 패키지(@docsagent/mcp-zotero)로도, PyPI의 Python 패키지(docsagent-mcp-zotero)로도 제공됩니다. 이미 쓰고 있는 런타임을 고르면 되고, 도구·스키마·에러 코드·쓰기 게이트는 완전히 동일합니다.
Zotero를 시작할 필요가 없습니다. C++ 코어가 ~/Zotero/zotero.sqlite와 storage/ 디렉터리를 직접 읽으므로, Zotero가 닫혀 있어도 —— 심지어 그 머신에 Zotero가 아예 설치되어 있지 않아도 —— 인덱싱과 검색이 계속 동작합니다.
호출마다 서브프로세스를 띄우는 게 아니라 상주 서비스입니다. 코어는 http://127.0.0.1:23120/rpc에서 백그라운드로 돌면서 라이브러리 변화에 맞춰 인덱스를 다시 만들고, MCP 클라이언트가 재시작되는 동안에도 워밍 상태를 유지합니다. 에이전트가 콜드 스타트 비용을 낼 일은 없습니다.
대형 라이브러리를 위해 설계되었습니다. 역색인 기반 BM25 전문 검색 + 구절 랭킹이 1,000편 이상의 PDF에서 약 15 ms, 메모리 사용량은 기가바이트가 아니라 수백 MB 수준입니다.
8개 MCP 도구(읽기 5 + 쓰기 3). JSON 스키마로 검증되는 인수, 토큰 예산, 결과 중복 제거, 그리고 3계층 쓰기 안전 게이트를 갖췄습니다.
두 가지 전송 방식. 로컬 MCP 클라이언트에는 stdio, 원격 배포 시에는 Streamable HTTP(/mcp)와 오리진 검사, API 키 또는 OAuth 2.0(RFC 7662) 인증, 요청별 RBAC를 제공합니다.
설정 파일 하나. ~/.docsagent/config.json을 JS 셸, Python 셸, C++ 코어가 공유합니다.

동작 방식: 하나의 네이티브 코어 위에 올라간 두 개의 셸

MCP Client (Claude Code / Claude Desktop / Cursor / Codex / Gemini CLI / Qwen Code / Cline)
        │  stdio (local)   or   Streamable HTTP  /mcp  (remote)
        ▼
MCP shell  ← @docsagent/mcp-zotero  (TypeScript)  or  docsagent-mcp-zotero  (Python)
   · spec-driven tool schemas, argument validation, token budget, dedup
   · write orchestration via the Zotero local API, write safety gate, RBAC
        │  JSON-RPC 2.0 over HTTP  ({coreHost}:{httpPort}/rpc)
        ▼
DocsAgent Core  (resident C++ engine)
   · reads ~/Zotero/zotero.sqlite + storage/ directly
   · builds & serves the full-text index (BM25 + passage ranking)

이 분리가 중요합니다. 셸은 얇습니다 —— 도구 스키마를 들고, 인수를 검증하고, 토큰 예산을 지키며, Zotero 파일은 전혀 건드리지 않습니다. 무거운 작업은 C++ 코어가 처리합니다. 그래서 같은 엔진이 npm 패키지와 PyPI 패키지에 바이트 단위로 동일한 동작을 제공할 수 있습니다.

빠른 시작: 3단계로 Zotero를 AI 에이전트에 연결하기

옵션 A —— JavaScript / npm

# 1. start the resident search core (background service)
npx @docsagent/mcp-zotero start
npx @docsagent/mcp-zotero status    # pid / endpoint / version

그런 다음 MCP 클라이언트 설정(Claude Desktop, Cursor, Cline, Qwen Code 등)에 서버를 추가하세요.

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "npx",
      "args": ["-y", "@docsagent/mcp-zotero"]
    }
  }
}

옵션 B —— Python

# 1. install the Python shell (ships the same bundled core binaries)
pip install docsagent-mcp-zotero
docsagent-mcp-zotero core start
docsagent-mcp-zotero core status

그리고 같은 방식으로 Python 셸을 등록하세요.

{
  "mcpServers": {
    "docsagent-zotero": {
      "command": "docsagent-mcp-zotero",
      "args": []
    }
  }
}

MCP 클라이언트를 재시작하고 "내 Zotero 라이브러리는 나트륨 이온 전지의 용량 열화에 대해 뭐라고 말하고 있나요?" 같은 질문을 던져 보세요. 에이전트가 search를 호출해 zotero:KEY 인용이 붙은 BM25 랭킹 구절을 받아오고, 열린 웹이 아니라 당신의 PDF를 근거로 답합니다.

두 CLI 모두 코어 생명주기 명령 —— start, stop, restart, status(Python은 이를 core 하위 명령으로 실행합니다. 예: docsagent-mcp-zotero core restart) —— 을 제공하며, /mcp를 네트워크로 서비스하고 싶을 때 쓰는 --transport streamable-http도 있습니다.

에이전트가 호출할 수 있는 8개 도구

도구	유형	하는 일
`list_sources`	읽기	검색 가능한 모든 소스와 그 기능, 문서 수를 나열합니다. 먼저 이것을 호출하세요.
`search`	읽기	항목, 주석, 노트를 아우르는 라이브러리 교차 검색. `ids` / `snippets` / `full` 깊이와 태그, 연도 범위, 항목 유형, 저자, 컬렉션 필터를 지원합니다.
`get_content`	읽기	항목 하나를 쿼리 기준으로 랭킹된 구절(`k`) 또는 오프셋 페이지네이션이 있는 전문으로 읽습니다.
`get_metadata`	읽기	메타데이터, 초록, 주석, 노트, 인용(BibTeX / CSL-JSON / 포맷팅).
`list_library`	읽기	컬렉션, 항목, 태그, 저장된 검색, 독립 노트를 탐색합니다.
`import_item`	쓰기	로컬 PDF를 가져오거나 DOI / ISBN / arXiv ID를 해석합니다. 선택적으로 컬렉션 자동 분류가 가능합니다.
`add_note`	쓰기	Markdown 노트를 Zotero 하위 노트로 항목에 기록합니다. 롤백을 지원합니다.
`batch_modify`	쓰기	최대 200개 항목에 걸쳐 컬렉션이나 태그를 일괄 추가·제거합니다.

enableWrites: true를 설정하지 않으면 쓰기 도구는 아예 등록되지 않습니다. 설정하더라도 확인되지 않은 호출은 미리보기만 반환하고 할당량을 소비하지 않으며, 확인된 쓰기는 속도 제한(기본 30/hour)을 받고, 20개를 넘는 batch_modify는 requiresConfirmation을 반환합니다. 에이전트는 하루 종일 라이브러리를 읽을 수 있지만, 조용히 고쳐 쓸 수는 없습니다.

성능: 10,000편의 PDF, 42 GB, 약 7분에 인덱싱 완료

이 MCP 서버의 코어는 PapersGPT의 검색 벤치마크를 뒷받침하는 것과 동일한 인덱싱·검색 엔진입니다. 실제 Zotero 설치 환경에서 측정한 수치는 다음과 같습니다.

라이브러리 규모	원본 데이터	인덱스 구축	평균 쿼리 시간	메모리(RSS)	인덱스 크기
1,000편의 PDF	4.2 GB	51.5 s	13.1 ms	353 MB	100 MB
10,000편의 PDF	42 GB	421 s(7 m 01 s)	19.5 ms	2.21 GB	901 MB

일부러 낮춘 사양 —— 4 cores / 8 GB RAM —— 에서 1,506편의 PDF(4.5 GB)를 인덱싱하는 데 141초가 걸렸고, 프로세스가 붙잡은 메모리는 227 MB, 평균 검색 시간은 ~15 ms였습니다. 중요한 패턴은 이것입니다.

인덱싱은 대체로 선형으로 확장됩니다. PDF가 열 배가 되면 구축 시간도 열 배 —— 그리고 그 비용은 새 문서마다 한 번만 내면 되지, 질문마다 내는 것이 아닙니다.
검색은 평평하게 유지됩니다. 1,000편에서 13 ms, 10,000편에서 19.5 ms. 논문을 더 넣는다고 에이전트가 느려지지 않습니다.
메모리는 적당하게 유지됩니다. 자동 오프로딩 덕분에 42 GB 라이브러리를 약 2 GB의 RAM 안에서 검색 가능한 상태로 유지합니다.
모든 것이 오프라인입니다. 인덱싱과 검색에 클라우드 호출이 없으므로 비행기 안에서도, 통제된 실험실 네트워크에서도, 수출 통제 상황에서도 동작합니다.

"Zotero를 시작할 필요가 없다"가 워크플로를 바꾸는 이유

전통적인 Zotero MCP 서버는 Zotero 로컬 API(http://localhost:23119/api)를 감싼 얇은 래퍼입니다. Zotero 프로세스가 없으면 답도 없습니다. 이 단일 의존성이 모든 것을 규정합니다 —— 컨테이너, 원격 개발 머신, 헤드리스 스크립트, SSH 세션에서는 라이브러리를 검색할 수 없고, Zotero가 동기화 중일 때는 검색할 수 없으며, 호출마다 인덱스 조회가 아니라 요청 왕복이 됩니다.

DocsAgent 코어는 데이터베이스를 직접 읽기 때문에, 워크플로의 "읽기" 절반이 Zotero 앱으로부터 분리됩니다.

	API 기반 Zotero MCP 서버	Zotero MCP Server 4.0
검색에 Zotero가 실행 중이어야 함	예	아니요
검색 백엔드	Zotero 로컬 API 호출	네이티브 C++ BM25 + 구절 인덱스
10,000편 PDF 쿼리 지연	수백 ms에서 수 초	~20 ms
런타임	보통 하나	JavaScript + Python
원격 / HTTP 전송	드묾	인증 + RBAC가 있는 Streamable HTTP
쓰기 안전성	보통 수동	3계층 게이트 + 속도 제한

솔직한 단서 하나: 쓰기는 여전히 Zotero 자체의 로컬 API를 거칩니다. 그래야 Zotero가 라이브러리의 단일 진실 공급원(single source of truth)으로 남기 때문입니다. 에이전트가 PDF를 가져오거나, 노트를 추가하거나, 항목 태그를 바꾸게 하려면 그 특정 단계에서는 Zotero가 실행 중이어야 합니다. 인덱싱, 검색, 읽기는 결코 그렇지 않습니다.

사용 사례: 연구자들이 실제로 어떻게 쓰는가

Claude Code나 Cursor로 편집기 안에서 하는 리서치. 논문을 쓰면서 에이전트가 당신의 라이브러리에서 구절, 초록, BibTeX를 바로 끌어오게 하세요 —— 복사·붙여넣기도, 브라우저 탭도 필요 없습니다.
Codex나 Gemini CLI로 하는 터미널 중심 문헌 분류. "내 라이브러리에서 전력 변환 효율이 20%를 넘는다고 보고한 논문을 모두 찾아서 Perovskite 컬렉션에 추가해 줘" —— search 다음에 batch_modify.
오프라인 읽기. 비행기나 현장에서 인덱스가 로컬로 쿼리에 답합니다. 네트워크가 필요 없습니다.
그룹 라이브러리. zoteroGroups를 연구실 공유 라이브러리로 지정하면 개인 컬렉션과 나란히 검색할 수 있습니다.
에이전트 스킬. 이 프로젝트는 이식 가능한 SKILL.md도 배포하므로, 스킬을 지원하는 에이전트에게 도구 인수를 추측하게 하는 대신 "검색 후 인용" 워크플로를 가르칠 수 있습니다.

프라이버시와 안전성

당신의 PDF는 절대 머신을 떠나지 않습니다. 인덱싱과 검색은 100% 로컬이며 어떤 문서도 클라우드 서비스로 전송되지 않습니다. 쓰기를 의도적으로 활성화하면 게이트가 적용되고, 미리보기가 가능하며, 속도가 제한되고, 되돌릴 수 있습니다. 서버를 의도적으로 HTTP에 노출하면 열린 포트 대신 오리진 검사, 토큰 인증, 요청별 RBAC를 얻습니다.

자주 묻는 질문

MCP 서버가 동작하려면 Zotero를 계속 실행해 두어야 하나요?

아니요 —— 검색과 읽기에는 필요하지 않습니다. 코어는 Zotero 데이터 디렉터리(zotero.sqlite와 storage/)를 직접 읽으므로 Zotero가 닫혀 있어도, 심지어 그 머신에서 Zotero 데스크톱 앱이 실행되고 있지 않아도 인덱싱과 검색이 동작합니다. Zotero 로컬 API를 거치는 것은 세 가지 쓰기 도구(항목 가져오기, 노트 추가, 태그·컬렉션 일괄 편집)뿐이므로, 그것들에는 Zotero가 열려 있어야 합니다.

Zotero MCP 서버는 JavaScript뿐 아니라 Python도 지원하나요?

네. 기능이 동등한 두 개의 셸이 있습니다. JavaScript/Node 사용자를 위한 npm의 @docsagent/mcp-zotero와 Python 3.10+를 위한 PyPI의 docsagent-mcp-zotero입니다. 둘 다 동일한 스키마, 에러 코드, 쓰기 게이트로 같은 8개 도구를 노출하며, 동일한 번들 C++ 코어를 관리합니다.

얼마나 큰 Zotero 라이브러리까지 감당할 수 있나요?

수천 편의 PDF를 가진 라이브러리는 일상적입니다. 1,000편의 PDF(4.2 GB)는 약 52초에 인덱싱되고 약 13 ms에 쿼리됩니다. 10,000편의 PDF(42 GB)는 약 7분에 인덱싱되고 약 19.5 ms에 쿼리됩니다. 인덱스 구축 시간은 라이브러리 규모에 대체로 비례해 늘어나지만, 쿼리 지연은 사실상 일정하게 유지됩니다.

내 Zotero 라이브러리가 어딘가에 업로드되나요?

아니요. 코어는 인덱스를 전적으로 당신의 머신에서 구축하고 제공하며, 검색에 네트워크 접근이 필요하지 않습니다. 당신의 논문에 관한 어떤 정보도 PapersGPT나 제3자에게 전송되지 않습니다.

AI 에이전트가 내 Zotero 라이브러리를 수정할 수 있나요?

당신이 허용한 경우에만 가능합니다. enableWrites가 true로 설정되지 않으면 쓰기 도구는 등록되지 않고, 확인되지 않은 호출은 미리보기를 반환하며, 확인된 쓰기는 속도 제한(기본 30/hour)을 받고, 20개를 넘는 다중 항목 배치는 명시적 확인을 요구합니다.

어떤 AI 클라이언트가 지원되나요?

모든 MCP 클라이언트입니다. 프로젝트는 Claude Desktop, Claude Code, Cursor, Codex, Cline, Gemini CLI, Qwen Code를 문서화하며, stdio 대신 원격으로 접속하는 클라이언트를 위해 Streamable HTTP 전송을 제공합니다.

이전 PapersGPT MCP 구성과는 어떻게 다른가요?

이전 구성은 Zotero 로컬 API를 중심으로 만들어진 단일 목적 브리지였습니다. 버전 4.0은 이를 상주하는 C++ 검색 코어로 교체하고, 일급 Python 셸을 추가했으며, Zotero가 실행되지 않아도 검색이 되게 만들고, 현실적인 상한을 "수백 편의 논문"에서 10,000편 이상의 PDF로 끌어올렸습니다. 예전 글은 역사적 참고 자료로 여전히 공개되어 있습니다.

시작하기

npx @docsagent/mcp-zotero start

이 명령 하나로 당신의 Zotero 라이브러리가, 이미 쓰고 있는 어떤 AI 에이전트에게든 비공개이고 밀리초 단위로 빠른 지식 기반이 됩니다. 설정 안내, 도구 스키마, 전체 설정 레퍼런스는 docsagent 저장소에 있고, 더 많은 배경은 MCP 서버 페이지에서 볼 수 있습니다.

같은 엔진을 Zotero 안에서 쓰고 싶나요 —— 앱 내 채팅, AutoPilot 일괄 읽기, 로컬 LLM? Zotero AI 플러그인 비교와 PapersGPT를 보세요. 터미널 중심 사용자라면 Zotero CLI 가이드도 함께 읽어 보세요.