notelm-mcp 1.2.1

package/docs/notebooklm-mcp-usage.qmd

@@ -0,0 +1,119 @@
+---
+title: "NotebookLM MCP 사용 가이드"
+date: "2026-01-03"
+author: "Assistant"
+format:
+  html:
+    toc: true
+    code-fold: false
+    theme: cosmo
+---
+
+# 개요
+
+**NotebookLM MCP**는 Google NotebookLM의 강력한 기능을 MCP(Model Context Protocol) 인터페이스를 통해 제공하는 서버입니다. 이를 통해 Claude Desktop, Cursor 등 MCP 호환 클라이언트에서 Gemini 3 모델과 대화하거나 나만의 노트북(Knowledge Base)을 활용할 수 있습니다.
+
+# 1. 설치 (Installation)
+
+이 프로젝트는 Node.js 기반의 MCP 서버입니다.
+
+### 요구 사항
+
+- Node.js v18.0.0 이상
+- Google 계정 (NotebookLM 접근용)
+
+### 실행 방법
+
+`npx`를 사용하여 별도의 설치 없이 바로 실행할 수 있습니다.
+
+```bash
+npx notebooklm-mcp
+```
+
+또는 소스 코드를 클론하여 빌드 후 실행할 수 있습니다.
+
+```bash
+git clone https://github.com/PleasePrompto/notebooklm-mcp.git
+cd notebooklm-mcp
+npm install
+npm run build
+node dist/index.js
+```
+
+# 2. 클라이언트 연동 (Configuration)
+
+Claude Desktop 등 MCP 클라이언트의 설정 파일(`claude_desktop_config.json`)에 다음과 같이 추가하세요.
+
+**중요:** 자동 로그인을 위해 Google 계정 정보를 환경 변수로 설정하는 것이 좋습니다.
+
+```json
+{
+  "mcpServers": {
+    "notebooklm": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "notebooklm-mcp"
+      ],
+      "env": {
+        "NOTEBOOK_URL": "https://notebooklm.google.com/notebook/YOUR_NOTEBOOK_ID",
+        "AUTO_LOGIN_ENABLED": "true",
+        "LOGIN_EMAIL": "your.email@gmail.com",
+        "LOGIN_PASSWORD": "your-app-password-or-regular-password",
+        "HEADLESS": "true"
+      }
+    }
+  }
+}
+```
+
+### 환경 변수 목록
+
+| 변수명 | 설명 | 기본값 |
+|--------|------|--------|
+| `NOTEBOOK_URL` | 기본으로 사용할 노트북 URL (선택 사항) | - |
+| `AUTO_LOGIN_ENABLED` | 자동 로그인 활성화 여부 (`true`/`false`) | `false` |
+| `LOGIN_EMAIL` | Google 로그인 이메일 | - |
+| `LOGIN_PASSWORD` | Google 로그인 비밀번호 | - |
+| `HEADLESS` | 브라우저 헤드리스 모드 여부 (`true`/`false`) | `true` |
+| `MAX_SESSIONS` | 최대 동시 세션 수 | `10` |
+| `SESSION_TIMEOUT` | 세션 타임아웃 (초) | `900` |
+| `STEALTH_ENABLED` | 봇 탐지 회피 기능 활성화 | `true` |
+
+# 3. 주요 기능 (Tools)
+
+NotebookLM MCP는 다음과 같은 도구들을 제공합니다.
+
+### 📝 질문 및 대화
+
+- **`ask_question`**: 지정된 노트북 또는 기본 노트북에 질문을 던지고 Gemini 3의 답변을 받습니다. 이전 대화 맥락을 유지하는 세션을 지원합니다.
+
+### 📚 노트북 관리
+
+- **`list_notebooks`**: 사용 가능한 모든 노트북 목록을 조회합니다.
+- **`get_notebook`**: 특정 노트북의 상세 정보(ID, 이름, 주제 등)를 조회합니다.
+- **`add_notebook`**: 새로운 노트북을 생성합니다.
+- **`select_notebook`**: 작업할 활성 노트북을 선택합니다.
+- **`update_notebook`**: 노트북의 정보를 수정합니다.
+- **`remove_notebook`**: 노트북을 삭제합니다.
+- **`search_notebooks`**: 쿼리 기반으로 관련 노트북을 검색합니다.
+
+### ⚙️ 세션 및 인증
+
+- **`setup_auth`**: 초기 인증을 수행합니다. (브라우저가 열려 직접 로그인할 수 있음)
+- **`list_sessions`**: 현재 활성화된 대화 세션 목록을 확인합니다.
+- **`close_session` / `reset_session`**: 세션을 종료하거나 초기화합니다.
+- **`cleanup_data`**: 브라우저 데이터를 정리합니다.
+
+# 4. 리소스 (Resources)
+
+MCP 리소스 기능을 통해 노트북 정보를 직접 읽어올 수 있습니다.
+
+- **`notebooklm://library`**: 전체 노트북 목록과 라이브러리 통계를 JSON 형식으로 반환합니다.
+- **`notebooklm://library/{id}`**: 특정 노트북의 메타데이터를 반환합니다.
+
+# 5. 문제 해결 (Troubleshooting)
+
+- **로그인 실패:** `HEADLESS="false"`로 설정하여 브라우저 창을 띄우고 직접 로그인 과정을 모니터링하세요. 2단계 인증이 필요한 경우 수동 개입이 필요할 수 있습니다.
+- **봇 탐지:** `STEALTH_ENABLED="true"` 설정이 켜져 있는지 확인하세요. 너무 잦은 요청은 일시적인 차단을 유발할 수 있습니다.
+- **권한 오류:** `setup_auth` 도구를 실행하여 인증 토큰을 갱신하세요.