Zotero 읽기 전용 MCP 브리지

각 참가자의 Zotero Desktop 라이브러리를 읽기 전용으로 검색하는 도구입니다. 기본 참가자 모드는 인터넷 공개나 ChatGPT 설정 없이 자기 컴퓨터에서 브라우저로 사용합니다. 고급 사용자는 같은 코드의 /mcp 엔드포인트를 ChatGPT 또는 다른 MCP 클라이언트에 연결할 수 있습니다.

지원 범위

도구는 다음 7개뿐이며 모두 이름과 설명에 read_only를 포함합니다.

• zotero_read_only_search_library

• zotero_read_only_get_recent_items

• zotero_read_only_get_item_metadata

• zotero_read_only_list_tags

• zotero_read_only_list_collections

• zotero_read_only_list_pdf_attachments

• zotero_read_only_search_pdf_full_text

서버는 Zotero에 읽기 요청만 보내며, 도구 allowlist 밖의 MCP 호출은 거부합니다. 논문/서지 레코드, 독립 PDF, 하위 첨부파일은 classification으로 구분합니다. 값이 없으면 정확히 확인되지 않음을 반환합니다.

Related MCP server: zotero-mcp

참가자에게 권장하는 사용법

1. GitHub의 Releases에서 Zotero-Read-Only-Assistant.exe를 받습니다.

2. Zotero Desktop을 설치하고 실행합니다.

3. Zotero에서 로컬 API 허용을 켭니다.

4. Zotero-Read-Only-Assistant.exe를 더블클릭합니다.

5. 검색 화면 열기를 누릅니다.

6. 브라우저에 Zotero 읽기 도우미가 열리면 검색합니다.

실행 파일에는 필요한 Python 환경이 포함됩니다. 참가자는 터미널, Python, 포트 번호, 인증 토큰, HTTPS 주소를 입력하지 않습니다.

구조

ChatGPT custom MCP app
        │ HTTPS + Bearer token 또는 OAuth를 종료하는 보안 터널
        ▼
참가자 PC의 bridge: 127.0.0.1:8787/mcp
        │ loopback HTTP 읽기 요청만
        ▼
Zotero Desktop Local API: 127.0.0.1:23119/api/

참가자마다 브리지와 토큰을 하나씩 사용해야 합니다. 하나의 중앙 서버가 여러 참가자의 로컬 Zotero를 직접 읽는 구조는 지원하지 않습니다.

개발자용 빠른 실행

1. Zotero Desktop에서 설정 → 고급 → 이 컴퓨터의 다른 애플리케이션이 Zotero와 통신하도록 허용을 켭니다.

2. Python 3.11 이상 환경에서 python -m venv .venv와 pip install -r requirements.txt를 실행합니다.

3. .env.example을 .env로 복사하고 32자 이상의 무작위 BRIDGE_AUTH_TOKEN을 설정합니다.

4. PowerShell에서 ./run.ps1을 실행합니다.

5. 외부 공개는 docs/installation.md의 보안 터널 절차로 구성합니다.

일반 참가자용 파일

일반 참가자에게는 저장소 전체가 아니라 프로젝트 폴더를 압축해 전달합니다. 참가자는 participant\Start-Participant.vbs를 더블클릭하고 Setup and Start 버튼만 누르면 브라우저 검색 화면을 사용할 수 있습니다. 자세한 안내는 docs/participant-installation.md에 있습니다.

ChatGPT 등록

ChatGPT의 사용자 지정 MCP 앱은 워크스페이스 정책과 요금제에 따라 Developer mode가 필요할 수 있습니다. 현재 UI에서 Settings → Apps → Create 또는 워크스페이스의 사용자 지정 앱 생성 메뉴를 열고 다음을 등록합니다.

• MCP server URL: https://<참가자-터널-호스트>/mcp

• 인증: Authorization: Bearer <BRIDGE_AUTH_TOKEN> 또는 조직의 OAuth 보호 프록시

• 권한: 읽기 전용 도구만 허용

UI가 고정 Bearer 헤더 입력을 제공하지 않고 OAuth만 허용하면, 브리지 앞에 OAuth 2.1/OIDC reverse proxy를 두고 /mcp로 전달할 때 내부적으로 Authorization: Bearer <BRIDGE_AUTH_TOKEN>을 주입합니다. 브리지 토큰은 ChatGPT 대화나 저장소에 넣지 않습니다.

검증

$env:BRIDGE_AUTH_TOKEN = "a-long-random-token-at-least-32-characters"
python -m pytest -q
python -m compileall app tests

운영 전 체크리스트는 docs/installation.md를 참고하세요. 테스트 프롬프트는 prompts/test-prompts.md에 있습니다.