# zotero-mcp

로컬 Zotero 라이브러리(`~/Zotero/zotero.sqlite` + `storage/`)를 Claude 같은 MCP 클라이언트에서 검색하고 읽을 수 있게 해 주는 MCP 서버입니다.
DOI나 arXiv ID로 새 논문을 추가하는 기능도 있습니다.

- **읽기**는 Zotero가 꺼져 있어도 동작합니다. DB를 임시 스냅샷으로 복사해서 읽으며, 원본 DB에는 절대 쓰지 않습니다.
- **추가**는 실행 중인 Zotero 앱의 로컬 커넥터(`127.0.0.1:23119`, 브라우저 확장 "Save to Zotero"가 쓰는 경로)를 통해 Zotero가 직접 저장합니다. 그래서 Zotero 동기화와 WebDAV 파일 동기화가 그대로 동작합니다.
  Zotero가 꺼져 있으면 사용자에게 켜 달라고 요청합니다(MCP elicitation을 지원하는 클라이언트에서는 확인 창, 그 외에는 안내 메시지).

## 도구

| 도구 | 설명 |
|---|---|
| `search_library` | 제목·저자·초록·학회명·DOI·태그·연도로 검색 (컬렉션/태그/유형/연도 필터 지원) |
| `search_fulltext` | PDF 본문 검색, 일치하는 구절 스니펫 반환 |
| `get_item` | 메타데이터, 초록, 첨부파일, 노트/주석 개수 |
| `get_fulltext` | 본문 전체 (offset으로 나눠 읽기) |
| `get_annotations` | Zotero 리더에서 단 하이라이트·코멘트 (페이지, 색상 포함) |
| `get_notes` | 하위 노트 |
| `list_collections` / `list_tags` | 컬렉션 트리, 태그 목록 |
| `add_paper` | DOI / arXiv ID로 논문 추가. 메타데이터는 arXiv·doi.org에서 가져오고, PDF는 arXiv나 지정한 URL에서 받거나 Zotero의 오픈액세스 검색으로 첨부. 컬렉션·태그·노트 지정, 중복 검사 |
| `import_citations` | BibTeX / RIS 등을 일괄 가져오기 |

본문은 Zotero가 만들어 둔 `.zotero-ft-cache`를 우선 사용하고, 캐시가 없으면 PDF/HTML에서 직접 추출합니다.

## 설치 및 등록

[uv](https://docs.astral.sh/uv/)가 필요합니다.

```bash
git clone https://github.com/ahnhyunjun417/zotero-mcp.git
```

Claude Code:

```bash
claude mcp add --scope user zotero -- uv run --directory "/path/to/zotero-mcp" zotero-mcp
```

Claude Desktop에서는 `claude_desktop_config.json`(Windows: `%APPDATA%\Claude\`)에 다음을 추가합니다:

```json
{
  "mcpServers": {
    "zotero": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\zotero-mcp", "zotero-mcp"]
    }
  }
}
```

## 환경 변수 (선택)

| 변수 | 용도 |
|---|---|
| `ZOTERO_DATA_DIR` | Zotero 데이터 폴더 (기본값 `~/Zotero`) |
| `ZOTERO_BASE_DIR` | 연결 파일(linked file)의 기준 폴더 |
| `ZOTERO_CONNECTOR_URL` | Zotero 커넥터 주소 (기본값 `http://127.0.0.1:23119`) |
| `ZOTERO_EXECUTABLE` | "Zotero를 대신 실행"에 쓸 실행 파일 경로 (기본값: 일반적인 설치 위치에서 자동 탐색) |
| `ZOTERO_WEBDAV_URL`, `ZOTERO_WEBDAV_USER`, `ZOTERO_WEBDAV_PASSWORD` | 로컬에 없는 첨부파일을 WebDAV에서 `KEY.zip`으로 받아오는 폴백. URL은 Zotero 동기화 설정의 WebDAV URL과 같은 값 |

Zotero 동기화 설정의 "파일 다운로드"가 "동기화 시"(기본값)이면 모든 파일이 로컬에 있으므로 WebDAV 폴백은 필요 없습니다.
"필요할 때"로 바꾸었거나 다른 PC에서 쓰는 경우에만 설정하세요. 비밀번호는 저장소가 아니라 MCP 클라이언트 설정의 `env`에만 넣으세요.

## 개인정보

- 라이브러리 내용은 외부 서버로 보내지 않습니다. 다만 도구 결과(검색 결과, 본문, 주석 등)는 MCP 클라이언트가 쓰는 LLM에 전달됩니다.
- 외부로 나가는 요청은 `add_paper`가 메타데이터와 PDF를 받을 때(arXiv, doi.org, 지정한 PDF URL), 그리고 WebDAV 폴백을 설정했을 때뿐입니다.
- DB 스냅샷은 OS 임시 폴더에 만들고, 서버가 종료되면 삭제합니다.