jacob-bd/notebooklm-mcp-cli 프로젝트는 Google NotebookLM에 프로그래밍 방식으로 접근할 수 있도록 돕는 도구로, Command-Line Interface(CLI)와 Model Context Protocol (MCP) 서버 기능을 단일 패키지로 통합하여 제공합니다. 이 프로젝트는 Pro/free tier 계정에서 테스트되었으며, 스크립팅, 자동화, 또는 AI 에이전트 연동을 목적으로 합니다.

핵심 방법론 (Core Methodology)

이 프로젝트는 Google NotebookLM의 비공개(undocumented) 내부 API를 활용하여 기능을 구현합니다. 이는 공식적인 API가 아니므로 Google의 변경에 따라 작동이 중단될 수 있는 위험을 내포합니다. 핵심적인 기술적 접근 방식은 다음과 같습니다:

1. 쿠키 기반 인증 (Cookie-based Authentication): NotebookLM에 접근하기 위해 사용자 브라우저에서 추출된 인증 쿠키를 사용합니다.
   • nlm login 명령어 또는 notebooklm-mcp-auth 스탠드얼론 도구를 통해 구현됩니다.
   • 자동 모드 (Auto mode): 헤드리스 Chrome 브라우저를 실행하여 사용자가 Google 계정에 로그인하게 하고, 이 과정에서 필요한 인증 쿠키와 세션 정보를 자동으로 추출합니다. 추출된 쿠키는 파일 시스템에 저장되어 재사용됩니다.
   • 수동 모드 (Manual mode): 사용자가 직접 추출한 쿠키 파일을 제공하여 인증하는 방식도 지원합니다.
   • 프로파일 관리 (Profile Management): 여러 Google 계정을 사용하는 사용자를 위해 각 계정별로 격리된 인증 프로파일을 생성하고 관리할 수 있습니다. 각 프로파일은 고유한 Chrome 세션을 가집니다.
2. 토큰 및 세션 관리 (Token and Session Management):
   • 쿠키 (Cookies): 일반적으로 2~4주마다 만료되며, 저장된 프로파일이 있는 경우 헤드리스 Chrome을 통해 자동 갱신을 시도합니다.
   • CSRF 토큰 (CSRF Token): 내부 API 호출 시 필요한 CSRF 토큰은 수분 내로 만료될 수 있습니다. 이 프로젝트는 API 요청 실패 시 자동으로 CSRF 토큰을 갱신하는 메커니즘을 내장하고 있습니다.
   • 세션 ID (Session ID): MCP 서버 시작 시 자동으로 추출되며, MCP 세션당 유효합니다.
   • 자동 토큰 만료 처리 (Automatic Token Expiration Handling): 버전 0.1.9부터는 CSRF 토큰 만료 시 즉시 갱신하고, 외부에서 쿠키 파일이 업데이트된 경우 디스크에서 쿠키를 다시 로드하며, 저장된 로그인 프로파일이 있는 경우 헤드리스 Chrome 인증을 실행하여 토큰 만료를 자동으로 처리합니다. refresh_auth() 함수를 통해 명시적인 토큰 재로딩도 가능합니다.

주요 기능 및 사용 방식

이 프로젝트는 두 가지 주요 인터페이스를 통해 NotebookLM 기능을 제공합니다:

3. CLI (nlm): 터미널에서 직접 명령어를 입력하여 NotebookLM의 다양한 기능을 제어합니다.
   • 노트북 관리: nlm notebook list (노트북 목록), nlm notebook create "Research Project" (노트북 생성)
   • 소스 추가: $nlm source add <notebook> --url "https://..."$ (URL, 텍스트, Google Drive, 파일 등의 소스 추가)
   • 콘텐츠 질의: nlm notebook query (AI 채팅을 통한 노트북 콘텐츠 질의)
   • 스튜디오 콘텐츠 생성: nlm studio create (팟캐스트, 비디오, 보고서 등 다양한 스튜디오 콘텐츠 생성)
   • 아티팩트 다운로드: $nlm download audio <notebook> <artifact-id>$ (생성된 아티팩트 다운로드)
   • 공유 관리: $nlm share public <notebook>$ (노트북 공개/비공개, 사용자 초대)
   • Google Drive 동기화: nlm source sync (Google Drive 소스 동기화)
   • 웹/드라이브 리서치: nlm research start (웹 또는 드라이브 기반 리서치 시작)
   • nlm --ai 명령어로 AI Assistant 기반의 종합적인 설명에 접근할 수 있습니다.

4. MCP 서버 (notebooklm-mcp): Claude, Gemini, Cursor와 같은 AI 어시스턴트에 NotebookLM 기능을 도구(tool) 형태로 연결합니다.
   • AI 어시스턴트의 설정 파일 또는 명령어를 통해 notebooklm-mcp를 MCP 서버로 등록합니다.
   • 등록 후에는 AI 어시스턴트에 "Create a notebook about quantum computing and generate a podcast"와 같은 자연어 명령어를 사용하여 NotebookLM 기능을 활용할 수 있습니다.
   • 총 31가지의 NotebookLM 관련 도구가 MCP를 통해 제공됩니다.

설치 및 업데이트

• uv 또는 pip를 사용하여 PyPI에서 notebooklm-mcp-cli 패키지를 설치합니다. uv tool install notebooklm-mcp-cli (권장).
• 설치 후 nlm (CLI), notebooklm-mcp (MCP 서버), notebooklm-mcp-auth (스탠드얼론 인증 도구) 세 가지 실행 파일이 제공됩니다.
• 레거시 버전(notebooklm-cli, notebooklm-mcp-server)을 사용하는 경우, 먼저 제거한 후 단일 통합 패키지를 uv tool install --force notebooklm-mcp-cli로 재설치하여 마이그레이션해야 합니다.
• 업그레이드 시 uv tool upgrade notebooklm-mcp-cli 또는 pip install --upgrade notebooklm-mcp-cli를 사용하며, 최신 버전이 설치되지 않는 문제가 발생하면 uv tool install --force notebooklm-mcp-cli를 사용합니다.

문제 해결 및 제한 사항

• Chrome DevTools MCP 문제: puppeteer-core 모듈 관련 npx 버그로 인해 MCP가 "no tools"로 표시될 수 있으며, pnpm을 사용하여 chrome-devtools-mcp를 실행하도록 설정을 변경하는 것으로 해결할 수 있습니다.
• 제한 사항:
  • 무료 계정의 경우 일일 약 50회 질의 제한과 같은 rate limit이 존재합니다.
  • 내부 API 사용으로 인해 Google의 변경에 따라 기능이 작동하지 않을 수 있습니다.
  • 쿠키는 수주마다 만료되어 재추출이 필요할 수 있습니다.

기여 (Contributing)

이 프로젝트는 "비개발자"가 AI 코딩 어시스턴트의 도움을 받아 개발되었음을 명시하고 있습니다. 따라서 코드가 완벽하지 않을 수 있음을 인정하며, 경험 많은 Python 개발자들의 코드 리팩토링, 오류 처리 개선, 타입 힌트 추가, 아키텍처 개선 등 다양한 형태의 기여를 환영합니다.