Skip to main content
Glama
deenesjakoruzh
introfini

MCP Server Zotero Dev

by introfini
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

MCP Server Zotero Dev

AI 어시스턴트에 Zotero 플러그인 개발을 위한 슈퍼파워를 부여하세요

License: MIT Zotero 7+

아키텍처 · 시작하기 · 사용 가능한 도구

Model Context Protocol (MCP) 서버로, Claude, Cursor, Windsurf 같은 AI 어시스턴트가 Zotero 7, 8, 9, 10 플러그인을 빌드, 테스트, 디버그할 수 있게 해줍니다. 스크린샷, DOM 상태, 디버그 로그, JavaScript 실행을 통해 AI는 상황을 이해할 풍부한 컨텍스트를 얻고, 문제를 해결하는 데 도움이 되는 도구를 사용할 수 있습니다.

✨ 기능

카테고리

기능

🎯 UI 검사

스크린샷, DOM 트리, 요소 찾기, 계산된 스타일

🖱️ UI 상호작용

요소 클릭 및 텍스트 입력 (shadow-DOM 인식)

💻 JS 실행

Zotero 컨텍스트에서 코드 실행, API 검사, 스니펫 테스트

🔧 빌드 도구

빌드, 서빙, 핫 리로드를 위한 스캐폴드 통합

📋 로그 및 오류

디버그 출력 스트리밍, 오류 콘솔, 문제 감시

🗃️ 데이터베이스

디버깅을 위한 zotero.sqlite 읽기 전용 접근

🔌 플러그인 관리

플러그인 설치, 리로드, 목록 조회

Related MCP server: Kaboom Browser AI Devtools MCP

🚀 빠른 시작

사전 요구 사항

  • Node.js 20+ 및 npm

  • Zotero 7+ — 모든 Zotero 7, 8, 9, 10 빌드(릴리스, 베타, 개발자 버전)에서 작동

  • 플러그인 개발용: zotero-plugin-scaffold

1. MCP 서버 설치

install-mcp를 사용하여 AI 어시스턴트에 서버를 추가하세요:

npx -y install-mcp @introfini/mcp-server-zotero-dev --client claude-code

지원 클라이언트: claude-code, cursor, windsurf, vscode, cline, roo-cline, claude, zed, goose, warp, codex

npx -y install-mcp @introfini/mcp-server-zotero-dev --client claude-code
npx -y install-mcp @introfini/mcp-server-zotero-dev --client cursor
npx -y install-mcp @introfini/mcp-server-zotero-dev --client vscode
npx -y install-mcp @introfini/mcp-server-zotero-dev --client windsurf

MCP 클라이언트 구성에 추가하세요:

{
  "mcpServers": {
    "zotero-dev": {
      "command": "npx",
      "args": ["-y", "@introfini/mcp-server-zotero-dev@1.1.1"],
      "env": {
        "ZOTERO_RDP_PORT": "6100"
      }
    }
  }
}

버전 및 업데이트: 위와 같이 정확한 버전을 고정하세요. 버전 없는 npx <pkg>는 npx가 캐시한 것을 계속 실행하며 새 릴리스를 가져오지 않으므로, 항상 버전과 -y를 포함하세요(-y가 없으면 npx가 설치 프롬프트를 기다리며 멈춥니다). 고정된 버전을 올리면 업그레이드되고, @latest를 사용하면 시작 시 항상 최신 버전을 가져옵니다(자동 업데이트되지만, 잘못된 릴리스가 자동으로 실행될 수 있고 매 시작마다 레지스트리 확인이 추가됩니다). install-mcp는 -y나 버전 없이 구성을 작성할 수 있으므로, 위의 수동 구성이 가장 견고한 방법입니다.

구성 추가 후 AI 어시스턴트를 재시작하세요.

2. Zotero에 MCP 브리지 플러그인 설치

zotero-mcp-bridge.xpi를 다운로드하고 설치하세요:

  1. Zotero에서: 도구 → 플러그인

  2. ⚙️ 클릭 → 파일에서 플러그인 설치

  3. 다운로드한 .xpi 파일 선택

  4. Zotero 재시작

이 경량 플러그인은 Zotero가 시작될 때 Remote Debugging Protocol을 활성화합니다. 한 번만 설치하면 되며 모든 Zotero 7+ 빌드(릴리스, beta, dev)에서 작동합니다.

3. 개발 시작!

Zotero를 평소처럼 열고 AI 어시스턴트에게 물어보세요:

"Zotero 스크린샷을 찍고 설치된 플러그인 목록을 보여줘"

그게 전부입니다! 특별한 실행 플래그도, 구성도 필요 없습니다. 🎉

🧰 사용 가능한 도구 (총 28개)

도구

설명

zotero_screenshot

창, 요소, 또는 영역 스크린샷 캡처

zotero_inspect_element

CSS 선택자로 요소 찾기

zotero_get_dom_tree

창/패널의 DOM 구조 가져오기

zotero_get_styles

요소의 계산된 CSS 스타일 가져오기

zotero_list_windows

열린 모든 Zotero 창 목록

스크린샷 대상: 메인 창, 환경설정, PDF 리더, 대화상자, 또는 선택자로 지정한 모든 요소. 캡처 전에 빨간 테두리를 추가하려면 highlightSelector를 사용하세요.

도구

설명

zotero_click_element

CSS 선택자로 요소 클릭 (툴바/메뉴 버튼, 환경설정 컨트롤, 목록 행). shadow DOM을 관통합니다; index는 여러 일치 항목 중 하나를 선택하고, mouseEvents는 전체 마우스 시퀀스를 합성합니다.

zotero_send_keys

입력/textarea/contenteditable에 텍스트 입력 (먼저 포커스하고 input/change 이벤트 발생). 선택적 clear 및 pressEnter.

해석은 먼저 light DOM을 시도한 다음 열린 shadow root를 관통합니다 (Zotero의 XUL 커스텀 요소는 내부를 shadow DOM에 유지합니다). 제한 사항: 차단 네이티브 모달 대화상자(Services.prompt.confirmEx)는 닫을 수 없습니다 — 중첩된 모달 루프가 이 도구가 실행되는 eval 스레드를 차단합니다.

도구

설명

zotero_execute_js

Zotero의 권한 있는 컨텍스트에서 JavaScript 실행. 최상위 return 문이 있는 코드를 IIFE로 자동 래핑.

zotero_inspect_object

Zotero API 탐색 - 모든 객체의 메서드와 속성 목록 (예: Zotero.Items)

zotero_open_preferences

Zotero 설정 창 열기, 선택적으로 특정 패널(내장 또는 플러그인)로 이동

zotero_search_prefs

패턴으로 환경 설정 검색/발견 (예: "debug"가 포함된 모든 설정 찾기)

zotero_get_pref

설정 값 가져오기

zotero_set_pref

설정 값 설정하기

예시: Zotero.Items.getAll(1), Zotero.Prefs.get('export.quickCopy.setting'), ZoteroPane.getSelectedItems()

팁: 코드를 작성하기 전에 zotero_inspect_object로 API를 탐색하세요. zotero_search_prefs로 설정 키를 발견하세요.

도구

설명

zotero_scaffold_build

플러그인 빌드 (개발 또는 프로덕션 모드)

zotero_scaffold_serve

핫 리로드가 있는 개발 서버 시작

zotero_scaffold_lint

플러그인 소스에 ESLint 실행

zotero_scaffold_typecheck

TypeScript 타입 검사 실행

도구

설명

zotero_read_logs

디버그 출력 읽기 (Zotero.debug)

zotero_read_errors

오류 콘솔 항목 읽기

zotero_watch_logs

실시간 로그 스트리밍

zotero_clear_logs

로그 버퍼 지우기

도구

설명

zotero_plugin_reload

개발 플러그인 핫 리로드

zotero_plugin_install

XPI 경로에서 플러그인 설치

zotero_plugin_list

버전/상태와 함께 설치된 플러그인 목록

도구

설명

zotero_db_query

zotero.sqlite에 SELECT 쿼리 실행

zotero_db_schema

테이블 스키마 정보 가져오기

zotero_db_stats

데이터베이스 통계 가져오기 (항목, 첨부 파일, 컬렉션, 크기)

참고: 데이터베이스 접근은 읽기 전용이며 Zotero가 닫혀 있어야 하거나, 데이터베이스의 복사본을 사용합니다.

🏗️ 아키텍처

┌─────────────────────────────────────────────────────────────────┐
│                        AI Assistant                             │
│                  (Claude, Cursor, Windsurf)                     │
└─────────────────────────┬───────────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌─────────────────────────────────────────────────────────────────┐
│                  MCP Server (Node.js/TypeScript)                │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────────────┐   │
│  │   Scaffold   │  │     RDP      │  │      Database        │   │
│  │  Integration │  │    Client    │  │      Reader          │   │
│  └──────────────┘  └──────┬───────┘  └──────────────────────┘   │
└─────────────────────────────┼───────────────────────────────────┘
                              │ Firefox RDP (port 6100)
                              ▼
┌─────────────────────────────────────────────────────────────────┐
│                      Zotero Application                         │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │            MCP Bridge for Zotero                         │   │
│  │         Starts DevToolsServer on launch                  │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │              Firefox DevTools Server (built-in)          │   │
│  │           JS Execution • DOM • Console • Screenshots     │   │
│  └──────────────────────────────────────────────────────────┘   │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │                   Your Plugin (dev)                      │   │
│  └──────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────┘

이 접근 방식이 좋은 이유는?

  • ✅ 경량 플러그인 — RDP만 활성화하고 나머지는 Firefox DevTools가 처리

  • ✅ 설치 후 구성 불필요 — 특별한 플래그 없이 Zotero를 평소처럼 열기만 하면 됨

  • ✅ 풍부한 AI 컨텍스트 — 스크린샷, DOM, 로그가 AI가 플러그인 상태를 이해하는 데 도움

  • ✅ 핫 리로드 — zotero-plugin-scaffold와 통합되어 즉각적인 피드백 제공

  • ✅ 전체 Zotero 접근 — 권한 있는 컨텍스트에서 모든 Zotero API 실행 가능

  • ✅ 크로스 플랫폼 — Linux, Windows, macOS에서 작동

🔧 환경 변수

변수

설명

기본값

ZOTERO_RDP_PORT

원격 디버깅 포트

6100

ZOTERO_RDP_HOST

디버깅 호스트

127.0.0.1

ZOTERO_DATA_DIR

Zotero 데이터 디렉토리 경로

자동 감지

ZOTERO_PROFILE_PATH

Zotero 프로필 경로

자동 감지

🔌 RDP 포트 변경

브리지는 기본적으로 포트 6100에서 수신합니다. 두 개의 Zotero 인스턴스를 동시에 실행하는 경우(예: 일반 프로필과 개발 프로필) 또는 다른 프로세스가 이미 6100을 사용하는 경우에만 변경하면 됩니다.

포트는 브리지의 양쪽 모두에 있으며, 양쪽이 동일해야 합니다.

1. Zotero 쪽 — 플러그인 설정 지정:

  1. 설정 → 고급 → 구성 편집기로 이동하고 경고를 수락

  2. extensions.mcp-rdp.port 검색

  3. 없으면 생성: 숫자 선택, 이름을 extensions.mcp-rdp.port로 지정하고 포트 입력

  4. Zotero 재시작 — 리스너는 시작 시에만 열립니다

유형에 주의하세요. 구성 편집기는 기본적으로 부울을 미리 선택합니다. 숫자로 전환하지 않고 설정을 생성하면 포트 대신 true가 저장되고, Zotero는 TCP 포트가 아닌 로컬 파이프에서 브리지를 엽니다 — 디버그 로그는 성공을 보고하지만 어떤 MCP 클라이언트도 연결할 수 없습니다.

2. 클라이언트 쪽 — MCP 클라이언트 구성에서 ZOTERO_RDP_PORT를 동일한 값으로 설정:

{
  "mcpServers": {
    "zotero-dev": {
      "command": "npx",
      "args": ["-y", "@introfini/mcp-server-zotero-dev@1.1.2"],
      "env": {
        "ZOTERO_RDP_PORT": "6101"
      }
    }
  }
}

양쪽을 모두 변경하거나 둘 다 변경하지 마세요. 한쪽만 변경하면 브리지가 끊어집니다: Zotero는 한 포트에서 수신하는데 클라이언트는 다른 포트로 계속 연결을 시도합니다.

실제로 두 인스턴스 실행

Zotero를 두 번째 실행하면 이미 열려 있는 창이 표시됩니다. Firefox처럼 새 인스턴스를 시작하는 대신 실행 중인 인스턴스로 전달됩니다. 두 번째 인스턴스에는 자체 프로필 및 -no-remote가 필요합니다:

# macOS; adjust the binary path on Windows/Linux
MOZ_NO_REMOTE=1 "/Applications/Zotero.app/Contents/MacOS/zotero" -P <profile-name> -no-remote

해당 프로필에 자체 extensions.mcp-rdp.port를 지정하면 두 브리지가 서로 간섭하지 않습니다. 9.0.6(6100 포트)과 10.0-beta.22(6101 포트)를 동시에 실행하여 검증했습니다.

MCP Bridge 플러그인 1.0.5 이상이 필요합니다. 1.0.4 및 이전 버전에서는 extensions.mcp-rdp.port가 잘못된 환경설정 분기에서 읽혀 조용히 무시되었으므로, 어떤 값을 설정해도 브리지는 6100에 유지되었습니다. 이전 빌드에서 사용자 지정 포트를 구성했다면 extensions.zotero.extensions.mcp-rdp.port로 저장됩니다. 이 이름도 여전히 작동하지만 위의 이름을 사용하는 것이 좋습니다.

브리지 비활성화

Config Editor에서 extensions.mcp-rdp.enabled를 false(Boolean)로 설정하고 Zotero를 다시 시작하세요. 플러그인은 설치된 상태로 유지되지만 리스너를 열지 않으며, true로 다시 설정하기 전까지 어떤 MCP 클라이언트도 Zotero에 연결할 수 없습니다.

📸 스크린샷 예시

// Capture main Zotero window
await zotero_screenshot({ target: 'main-window' });

// Capture your plugin's panel with highlight
await zotero_screenshot({
  target: 'element',
  selector: '#my-plugin-panel',
  highlightSelector: '#my-plugin-button'
});

// Capture a specific window by ID (use zotero_list_windows to find IDs)
await zotero_screenshot({
  target: 'window',
  windowId: 12345
});

// Capture element after triggering UI action
await zotero_execute_js({ code: 'document.querySelector("#menu").click()' });
await zotero_screenshot({ target: 'element', selector: 'menupopup[state="open"]' });

🧑💻 개발

# Clone and install
git clone https://github.com/introfini/mcp-server-zotero-dev.git
cd mcp-server-zotero-dev
npm install

# Build everything
npm run build

# Build individual packages
npm run build:server
npm run build:plugin

# Run tests
npm test

# Development mode (watch)
npm run dev
mcp-server-zotero-dev/
├── packages/
│   ├── mcp-server/               # MCP server (npm package)
│   │   ├── src/
│   │   │   ├── index.ts          # MCP server entry
│   │   │   ├── rdp/              # RDP client
│   │   │   ├── tools/            # Tool implementations
│   │   │   └── prompts/          # Slash commands
│   │   └── package.json
│   │
│   └── zotero-plugin-mcp-rdp/    # Tiny Zotero plugin (.xpi)
│       ├── src/
│       │   └── bootstrap.js      # Starts RDP server (shipped verbatim)
│       ├── addon/
│       │   └── manifest.json
│       └── package.json
│
├── docs/                         # Documentation
└── package.json                  # Monorepo root

📚 리소스

🤝 기여

기여는 언제나 환영합니다. 시작하기 전에 알아두면 좋은 설정, 테스트 규칙, 코드베이스별 규칙은 **CONTRIBUTING.md**를 참조하세요.

간단히 요약하면:

  1. 기존 코드 패턴을 따르세요

  2. 새 기능에 대한 테스트를 추가하고, Zotero가 실행 중이 아닐 때는 실패하지 않고 건너뛰세요

  3. 문서를 업데이트하세요

  4. CI가 없으므로 npm run build, npm run typecheck, npm run lint, npm test를 직접 실행하고, PR에 어떤 Zotero 버전으로 검증했는지 명시하세요

📄 라이선스

MIT © introfini

감사의 글

  • Zotero 플러그인 개발자 커뮤니티를 위해 제작되었습니다

  • @windingwind의 zotero-plugin-scaffold와 통합됩니다

  • 안정적인 통신을 위해 Firefox DevTools RDP를 활용합니다

This server cannot be installed

A
license - permissive license
Not graded
quality - not tested
A
maintenance

How are these scores calculated?

Maintenance

–Maintainers
4hResponse time
5wRelease cycle
6Releases (12mo)
Commit activity
Issues opened vs closed

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Servers

View all related MCP servers

Related MCP Connectors

  • sncro

    Live browser debugging for AI assistants — DOM, console, network via MCP.

  • hithereiamaliff-mcp-nextcloud

    A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…

  • slima

    MCP Server for Slima - AI Writing IDE for Novel Authors with AI Beta Reader.

View all MCP Connectors

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/introfini/mcp-server-zotero-dev'

If you have feedback or need assistance with the MCP directory API, please join our Discord server