54yyyu/zotero-mcp

Zotero MCP는 Model Context Protocol (MCP)을 통해 사용자의 Zotero 연구 라이브러리를 ChatGPT, Claude 및 기타 AI 어시스턴트(예: Cherry Studio, Chorus, Cursor)와 원활하게 연결합니다. 논문을 검토하고, 요약을 생성하며, 인용을 분석하고, PDF 주석을 추출하는 등의 작업을 수행할 수 있습니다!

**벡터 기반 유사도 검색 (Vector-based similarity search)**을 전체 연구 라이브러리에 대해 수행할 수 있습니다 ([semantic] 추가 기능 필요)

다양한 임베딩 모델 (Multiple embedding models): 기본값 (무료, 로컬), OpenAI, Gemini
지능형 결과 (Intelligent results): 유사도 점수 및 문맥 매칭 제공
자동 업데이트 데이터베이스 (Auto-updating database): 구성 가능한 동기화 일정 제공

• 제목, 저자 또는 내용을 통해 논문, 기사 및 도서 검색

• 여러 기준을 사용한 복잡한 검색 수행

• 컬렉션(Collections), 태그 및 최근 추가 항목 탐색

• 개념 및 주제 기반 발견을 위한 시맨틱 검색 (Semantic search)

• 모든 항목에 대한 상세 메타데이터 검색 (Markdown 또는 BibTeX 내보내기)

• 전체 텍스트 내용 가져오기 (사용 가능한 경우)

• BetterBibTeX 인용 키(citation key)로 항목 조회

• 페이지 번호와 함께 PDF 주석 추출 및 검색

• Zotero의 기본 주석에 접근

• 노트 및 주석 생성 및 업데이트

• PDF 목차 / 개요 추출 ([pdf] 추가 기능 필요)

DOI로 논문 추가: 메타데이터 자동 가져오기 및 오픈 액세스 PDF 캐스케이드(Unpaywall, arXiv, Semantic Scholar, PMC) 지원
URL로 논문 추가: arXiv, DOI 링크, 일반 웹페이지 또는 로컬 파일로부터 추가

• 컬렉션 생성 및 관리, 항목 메타데이터 업데이트, 태그 일괄 업데이트
• 중복 항목 찾기 및 미리보기(dry-run)를 통한 병합
  하이브리드 모드 (Hybrid mode): 로컬 모드 사용자를 위한 로컬 읽기 + 웹 API 쓰기 방식

인용 통계 (Citation tallies): 각 항목을 지지, 대조 또는 언급하는 논문의 수를 확인 — Scite Zotero 플러그인의 MCP 버전
철회 알림 (Retraction alerts): 라이브러리를 스캔하여 철회되거나 수정된 논문 확인 - Scite 계정이 필요하지 않으며 공개 API 엔드포인트를 사용합니다.

• 오프라인 액세스를 위한 로컬 모드 (API 키 불필요)

• 클라우드 라이브러리 액세스를 위한 웹 API

• 하이브리드 모드: 로컬 Zotero에서 읽고 웹 API를 통해 쓰기

• 터미널에서 직접 라이브러리를 검색(Search), 탐색(browse), 편집(edit) — AI 어시스턴트 불필요

• 스크립팅(scripting), 자동화(automation), 빠른 조회(quick lookups)에 이상적

• 대화형 사용을 위한 짧은 별칭(aliases) (s, g, ann, coll) 제공

커맨드 라인(command line)이 처음이신가요? 커뮤니티에서 제작한 Zotero MCP Setup을 사용해 보세요 — macOS용 GUI 설치 프로그램(DMG), Mac/Windows용 원클릭 설치 스크립트, 그리고 단계별 가이드가 포함되어 있습니다. 터미널(Terminal) 경험이 없어도 됩니다.

기본 설치는 가볍습니다 — 검색, 메타데이터 검색(metadata retrieval), 주석(annotations), 쓰기 작업(write operations)을 포함합니다. ML/AI 의존성(dependencies)은 포함되지 않습니다.

uv tool install zotero-mcp-server
zotero-mcp setup # 자동 설정 (Claude Desktop 지원)

pip install zotero-mcp-server
zotero-mcp setup # 자동 설정 (Claude Desktop 지원)

pipx install zotero-mcp-server
zotero-mcp setup # 자동 설정 (Claude Desktop 지원)

기본 설치가 빠르고 작게 유지될 수 있도록 무거운 ML/PDF 의존성(dependencies)은 선택적 추가 기능(optional extras)으로 분리되어 있습니다:

추가 기능 (Extra)	추가되는 내용	설치 명령어
semantic	ChromaDB, sentence-transformers, OpenAI/Gemini 임베딩(embeddings)을 통한 시맨틱 검색(Semantic search)	pip install "zotero-mcp-server[semantic]"
pdf	PDF 목차 추출(PyMuPDF) 및 EPUB 주석(annotation) 지원	pip install "zotero-mcp-server[pdf]"
scite	Scite 인용 지능(citation intelligence) — 인용 횟수 집계 및 철회(retraction) 알림 (계정 불필요)	pip install "zotero-mcp-server[scite]"
all	위의 모든 기능	pip install "zotero-mcp-server[all]"

예를 들어, uv를 사용하는 경우:

uv tool install "zotero-mcp-server[all]" # 모든 기능을 포함한 전체 설치
uv tool install "zotero-mcp-server[semantic]" # 시맨틱 검색만 설치

기본적인 라이브러리 액세스(검색, 읽기, 주석, 쓰기)만 필요한 경우, 추가 기능이 없는 기본 설치만으로 충분합니다.

스마트 업데이트 명령어를 사용하여 zotero-mcp를 최신 상태로 유지하세요:

# 업데이트 확인
zotero-mcp update --check-only
# 최신 버전으로 업데이트 (모든 설정 유지)
...

Zotero MCP에는 이제 키워드뿐만 아니라 개념과 의미를 기반으로 연구 자료를 찾을 수 있는 강력한 AI 기반 시맨틱 검색 (Semantic Search) 기능이 포함되었습니다.

설정 과정 중 또는 별도로 시맨틱 검색을 구성하세요:

# 초기 설정 중에 구성 (권장)
zotero-mcp setup
# 또는 시맨틱 검색을 별도로 구성
...

사용 가능한 임베딩 모델 (Embedding Models):

기본값 (all-MiniLM-L6-v2): 무료이며 로컬에서 실행됩니다. 대부분의 사용 사례에 적합합니다.
OpenAI: 더 높은 품질을 제공하며 API 키가 필요합니다 (text-embedding-3-small 또는 text-embedding-3-large).
Gemini: 더 높은 품질을 제공하며 API 키가 필요합니다 (gemini-embedding-001).

업데이트 빈도 옵션:

수동 (Manual): zotero-mcp update-db를 실행할 때만 업데이트합니다.
시작 시 자동 (Auto on startup): 서버가 시작될 때마다 데이터베이스를 업데이트합니다.
매일 (Daily): 하루에 한 번 자동으로 업데이트합니다.
N일마다 (Every N days): 사용자 정의 간격을 설정합니다.

설정 후, 검색 데이터베이스를 초기화하세요:

# 시맨틱 검색 데이터베이스 구축 (빠름, 메타데이터 전용)
zotero-mcp update-db
# 전체 텍스트 추출을 포함하여 구축 (느림, 더 포괄적임)
...

AI 어시스턴트에서의 시맨틱 쿼리 (Semantic Queries) 예시:

*"신경과학에서의 머신러닝 (Machine Learning) 개념과 유사한 연구를 찾아줘"
*"기후 변화가 농업에 미치는 영향에 대해 논의하는 논문"
*"양자 컴퓨팅 (Quantum Computing) 응용과 관련된 연구"
*"소셜 미디어가 정신 건강에 미치는 영향에 관한 연구"
*"다음 초록과 개념적으로 유사한 논문을 찾아줘: [초록 붙여넣기]"

시맨틱 검색은 단순한 키워드 매칭이 아닌 개념적 이해를 바탕으로 유사도 점수 (Similarity Scores)를 제공하고 논문을 찾아줍니다.

전체 문서는 Zotero MCP docs에서 확인할 수 있습니다.

요구 사항

• Python 3.10 이상
• Zotero 7 이상 (전체 텍스트 접근이 가능한 로컬 API용)
• MCP 호환 클라이언트 (예: Claude Desktop, ChatGPT Developer Mode, Cherry Studio, Chorus)

ChatGPT 설정을 위한 경우: 시작 가이드를 참조하세요.

설치 후 다음 중 하나를 수행하세요:

• 자동 구성 (Auto-configure) (권장): zotero-mcp setup
• 수동 구성 (Manual configuration): claude_desktop_config.json에 추가

{ "mcpServers": { "zotero": { "command": "zotero-mcp", "env": { "ZOTERO_LOCAL": "true", "ZOTERO_API_KEY": "YOUR_API_KEY", "ZOTERO_LIBRARY_ID": "YOUR_LIBRARY_ID" } } } }

**로컬 읽기 전용 사용 (local read-only use)**의 경우, ZOTERO_LOCAL: "true" 설정만 있으면 충분합니다. ZOTERO_API_KEY와 ZOTERO_LIBRARY_ID 줄은 완전히 삭제해도 됩니다. 이 설정들은 **쓰기 모드 (write mode)**를 활성화할 때만 추가하세요. 로컬 API는 빠르지만 읽기 전용이므로, 서버는 쓰기 작업을 위해 Zotero 웹 API를 사용합니다.

• https://www.zotero.org/settings/security#applications 에서 API 키를 생성하세요.
• ZOTERO_LIBRARY_ID는 동일한 페이지에 표시되는 숫자로 된 **사용자 ID (userID)**입니다. (그룹 라이브러리의 경우, 그룹 ID를 사용하고 ZOTERO_LIBRARY_TYPE: "group"도 설정해야 합니다.)

팁 (Tip): 만약 Claude Desktop에서 zotero-mcp 명령어를 찾을 수 없다고 보고하면, 대신 절대 경로를 사용하세요 (zotero-mcp setup-info 또는 which zotero-mcp를 실행하여 경로를 확인하세요). GUI 앱은 항상 사용자의 셸 PATH를 상속받는 것은 아닙니다.

• Zotero 데스크톱을 실행합니다 (환경설정에서 로컬 API가 활성화되어 있는지 확인하세요).
• Claude Desktop을 실행합니다.
• Claude Desktop의 도구(tools) 인터페이스를 통해 Zotero-MCP 도구에 접속합니다.

프롬프트 예시:

• "내 라이브러리에서 머신러닝 (machine learning)에 관한 논문을 검색해줘"
• "내가 최근에 추가한 기후 변화 (climate change) 관련 기사를 찾아줘"
• "내 양자 컴퓨팅 (quantum computing) 논문의 주요 연구 결과를 요약해줘"
• "내 신경망 (neural networks) 논문에서 모든 PDF 주석 (annotations)을 추출해줘"
• "내 노트와 주석에서 '강화학습 (reinforcement learning)'이 언급된 부분을 검색해줘"
• "내 라이브러리에서 '#Crypt' 태그가 포함된 것을 제외하고 '#Arm' 태그가 붙은 논문을 보여줘"
• "'#Arm' 태그가 붙은 운영 체제 (operating system) 관련 논문을 검색해줘"
• "머신러닝 관련 논문의 BibTeX 인용 정보를 내보내줘"
• "컴퓨터 비전 (computer vision) 분야에서 딥러닝 (deep learning)과 개념적으로 유사한 논문을 찾아줘" (시맨틱 검색 (semantic search))
• "AI와 헬스케어 (healthcare)의 교차점과 관련된 연구를 찾아줘" (시맨틱 검색 (semantic search))
• "다음 초록과 유사한 주제를 다루는 논문을 찾아줘: [텍스트 붙여넣기]" (시맨틱 검색 (semantic search))

Settings -> MCP Servers -> Edit MCP Configuration으로 이동하여 다음을 추가하세요:

{
"mcpServers": {
"zotero": {
...

그 다음 "Save"를 클릭하세요.

Cherry Studio는 일반 설정 및 도구 선택을 위한 시각적 구성 방법도 제공합니다.

Web API를 통해 Zotero 라이브러리에 접속하는 방법 (원격 설정 시 유용):

zotero-mcp setup --no-local --api-key YOUR_API_KEY --library-id YOUR_LIBRARY_ID

Zotero 연결 (Zotero Connection):

ZOTERO_LOCAL=true
: 로컬 Zotero API를 사용합니다 (기본값: false)

ZOTERO_API_KEY
: Zotero API 키 (Web API용)

ZOTERO_LIBRARY_ID
: Zotero 라이브러리 ID (Web API용)

ZOTERO_LIBRARY_TYPE
: 라이브러리 유형 (user 또는 group, 기본값: user)

ZOTERO_WEBDAV_URL
: 원격 모드에서 첨부 파일을 직접 다운로드하기 위한 선택적 WebDAV 폴더 URL

ZOTERO_WEBDAV_USERNAME
: 선택적 WebDAV 사용자 이름

ZOTERO_WEBDAV_PASSWORD
: 선택적 WebDAV 비밀번호

시맨틱 검색 (Semantic Search):

ZOTERO_EMBEDDING_MODEL
: 사용할 임베딩 모델 (default, openai, gemini)

OPENAI_API_KEY
: OpenAI API 키 (OpenAI 임베딩용)

OPENAI_EMBEDDING_MODEL
: OpenAI 모델 이름 (text-embedding-3-small, text-embedding-3-large)

OPENAI_BASE_URL
: 사용자 정의 OpenAI 엔드포인트 URL (선택 사항, 호환 가능한 API와 함께 사용)

GEMINI_API_KEY
: Gemini API 키 (Gemini 임베딩용)

GEMINI_EMBEDDING_MODEL
: Gemini 모델 이름 (gemini-embedding-001)

GEMINI_BASE_URL
: 사용자 정의 Gemini 엔드포인트 URL (선택 사항, 호환 가능한 API와 함께 사용)

ZOTERO_DB_PATH
: 사용자 정의 zotero.sqlite 경로 (선택 사항)

# 서버를 직접 실행
zotero-mcp serve
# 전송 방법 지정
...

zotero-cli는 Zotero 라이브러리에 접근하기 위한 독립적인 터미널 인터페이스입니다. MCP 서버와 동일한 도구를 사용하지만 AI 어시스턴트가 필요하지 않습니다. 빠른 조회, 셸 스크립트(shell scripts) 및 자동화에 유용합니다.

AI 클라이언트가 MCP를 지원하는 경우(Claude Desktop, ChatGPT)에는 zotero-mcp를 사용하세요. zotero-cli를 사용하세요.

셸 스크립트(shell scripts), 크론 잡(cron jobs), 또는 셸 액세스 권한이 있는 에이전트 파이프라인(agentic pipelines, 예: Claude Code)의 경우에는 zotero-cli를 사용하세요. CLI 명령은 MCP 도구 스키마(tool schemas)보다 토큰을 훨씬 적게 소모하며 Unix 파이프(pipes)와 자연스럽게 결합됩니다.

두 방식 모두 zotero-mcp setup을 통해 설정된 동일한 구성 세트를 공유합니다.

# 검색
zotero-cli search "machine learning" # 키워드 검색
zotero-cli s "neural networks" --limit 5 # 짧은 별칭(alias), 결과 제한
...

진행 메시지(예: 어떤 API 호출이 이루어지는지)를 확인하려면 어디에서든 -v를 추가하세요:

zotero-cli -v search "CRISPR"

Zotero MCP에는 고급 PDF 주석 추출(annotation extraction) 기능이 포함되어 있습니다:

직접 PDF 처리 (Direct PDF Processing): Zotero에 아직 인덱싱되지 않은 경우에도 PDF 파일에서 직접 주석을 추출합니다.
향상된 검색 (Enhanced Search): PDF 주석 및 코멘트를 통해 검색합니다.
이미지 주석 지원 (Image Annotation Support): PDF에서 이미지 주석을 추출합니다.
원활한 통합 (Seamless Integration): Zotero의 기본 주석 시스템과 함께 작동합니다.

최적의 주석 추출을 위해 Zotero용 Better BibTeX 플러그인을 설치하는 것을 강력히 권장합니다. 주석 관련 기능은 주로 이 플러그인을 사용하여 테스트되었으며, 플러그인이 설치되어 있을 때 향상된 기능을 제공합니다.

PDF 주석 기능을 처음 사용하는 경우, 필요한 도구들이 자동으로 다운로드됩니다.

Zotero MCP는 이제 라이브러리 내 아이템 간의 관계(relationships)를 관리하는 기능을 지원합니다. 이는 관련 논문을 연결하거나, 버전을 추적하거나, 프리프린트(preprints)를 출판된 버전과 연결하는 데 유용합니다.

zotero_get_item_related(item_key="ABCD1234")

두 아이템 사이에 양방향 링크를 생성합니다:

zotero_add_item_relation(
item_key="ABCD1234",
related_item_key="EFGH5678",
...

zotero_remove_item_relation(
item_key="ABCD1234",
related_item_key="EFGH5678",
...

관계 유형 (Relation Types):

dc:relation
— 일반적인 관련 아이템 (기본값)

owl:sameAs
— 동일한 저작물인 아이템 (예: 프리프린트와 출판된 버전)

zotero_semantic_search
: 임베딩 모델(embedding models)을 사용한 AI 기반 유사도 검색

zotero_update_search_database

: 시맨틱 검색 데이터베이스(semantic search database)를 수동으로 업데이트합니다.

zotero_get_search_database_status

: 데이터베이스 상태 및 설정을 확인합니다.

zotero_search_items

: 키워드로 라이브러리를 검색합니다.

zotero_advanced_search

: 여러 기준을 사용하여 복합적인 검색을 수행합니다.

zotero_get_collections

: 컬렉션(collections) 목록을 가져옵니다.

zotero_get_collection_items

: 컬렉션 내의 아이템들을 가져옵니다.

zotero_get_tags

: 모든 태그(tags) 목록을 가져옵니다.

zotero_get_recent

: 최근에 추가된 아이템들을 가져옵니다.

zotero_search_by_tag

: 사용자 정의 태그 필터를 사용하여 라이브러리를 검색합니다.

zotero_get_item_metadata

: 상세 메타데이터(metadata)를 가져옵니다 (format="markdown", 전체 원본 Zotero 메타데이터를 위한 format="json", 그리고 format="bibtex" 지원)

zotero_get_item_fulltext

: 전체 텍스트(full text) 콘텐츠를 가져옵니다.

zotero_get_item_children

: 첨부 파일(attachments) 및 노트(notes)를 가져옵니다.

zotero_get_annotations