notebooklm-py 소개
notebooklm-py 는 Google의 노트북 기반 연구 도구인 NotebookLM 을 Python 코드와 명령줄(CLI) 환경에서 그대로 사용할 수 있도록 만든 비공식(Unofficial) 클라이언트 라이브러리입니다. NotebookLM 은 사용자가 제공한 PDF, 웹 페이지, 동영상, Google Drive 문서 같은 소스를 바탕으로 채팅과 오디오 개요(Audio Overview), 영상 개요, 슬라이드, 인포그래픽 등을 자동 생성하는 도구지만, 공식 인터페이스는 웹 UI 한 가지뿐이라 대량의 자료를 일괄 처리하거나 AI 에이전트와 결합해 쓰기에는 제약이 컸습니다. notebooklm-py 는 NotebookLM 이 내부적으로 사용하는 비공개(undocumented) API 엔드포인트를 분석해 동일한 기능을 Python API, CLI, 그리고 Agent Skill 형태로 노출함으로써 이러한 제약을 우회할 수 있게 합니다. 이 라이브러리는 Google 과 제휴 관계가 없는 커뮤니티 프로젝트이며, NotebookLM 의 내부 API 가 예고 없이 바뀌면 동작이 중단될 수 있다는 점도 README 상단에 명확히 안내되어 있습니다. 따라서 운영 서비스의 핵심 의존성으로 쓰기보다는 프로토타입, 연구 자동화, 개인용 도구로 활용하기에 적합합니다.
이 프로젝트가 흥미로운 이유는 단순한 API 래퍼(wrapper)에 머무르지 않고 AI 에이전트(Agent) 통합을 정식 사용 시나리오로 제시하기 때문입니다. notebooklm-py 는 저장소 루트에 NotebookLM 사용법을 정리한 SKILL.md 파일을 포함하고, notebooklm skill install 명령으로 Claude Code 의 ~/.claude/skills/notebooklm 디렉토리와 범용 .agents/skills/notebooklm 디렉토리에 이 스킬을 설치합니다. npx skills add teng-lin/notebooklm-py 명령으로는 같은 스킬을 GitHub 에서 바로 가져올 수 있고, 저장소의 AGENTS.md 에는 OpenAI Codex 와 같은 에이전트가 따라야 할 지침이 별도로 정리되어 있습니다. 즉, 사용자는 "이 PDF 다섯 개를 NotebookLM 노트북에 올리고, 오디오 개요를 만든 다음 MP3 로 저장해 줘" 같은 자연어 명령을 Claude Code 나 OpenClaw 에 입력하는 것만으로 NotebookLM 의 일련의 작업을 자동화할 수 있습니다.
기술 스택 측면에서 notebooklm-py 는 Python 3.10 이상을 지원하며, NotebookLM 의 비공개 RPC 호출을 위해 비동기(async) 방식의 NotebookLMClient 를 제공합니다. 인증(Authentication)은 Playwright 로 띄운 Chromium 또는 Microsoft Edge 에서 Google 로그인을 수행한 뒤 결과 쿠키를 storage_state.json 파일로 저장하는 방식이며, 이미 로그인된 브라우저 세션의 쿠키를 그대로 재사용하는 --browser-cookies chrome 옵션도 갖추고 있습니다. 라이브러리만 임베드해서 쓰고 싶은 사용자는 Playwright 없이 약 10 MB 의 의존성만 추가한 채 미리 확보한 storage_state.json 만 함께 배포하면 됩니다. PyPI 배지 기준 macOS, Linux, Windows 모두 CI 에서 검증되고 있어 일반적인 개발 환경에서 비교적 쉽게 도입할 수 있습니다.
notebooklm-py 가 제공하는 NotebookLM 기능 범위
notebooklm-py 의 가장 큰 장점은 NotebookLM 웹 UI 가 노출하는 거의 모든 기능과, UI 에는 없는 일부 기능까지 함께 다룬다는 점입니다. 노트북 관리에서는 노트북 생성, 목록 조회, 이름 변경, 삭제와 같은 기본 CRUD 동작을 모두 지원합니다. 소스 추가는 URL, YouTube, PDF·텍스트·Markdown·Word·EPUB·오디오·비디오·이미지 같은 파일, Google Drive 의 문서, 그리고 직접 붙여 넣은 텍스트까지 처리할 수 있고, 추가한 소스를 새로 고치거나 가이드(guide) 및 전체 텍스트(fulltext) 를 다시 가져오는 동작도 포함됩니다. 채팅(Chat) 영역에서는 단일 질의(question), 대화 기록(conversation history) 조회, 사용자 지정 페르소나(persona) 설정이 가능합니다.
NotebookLM 의 핵심 기능인 콘텐츠 생성(Content Generation)도 거의 모든 종류의 산출물(artifact) 을 다룹니다. 오디오 개요(Audio Overview) 는 deep-dive, brief, critique, debate 의 네 가지 형식과 세 가지 길이, 50 개 이상의 언어 설정을 지원하고, MP3 또는 MP4 로 내려받을 수 있습니다. 영상 개요(Video Overview) 는 explainer, brief, cinematic 등 세 가지 포맷에 아홉 가지 비주얼 스타일을 제공하며, 별도의 cinematic-video CLI 별칭도 마련되어 있습니다. 그 외에 슬라이드 덱(PDF 또는 PPTX), 퀴즈(Quiz, JSON·Markdown·HTML), 플래시카드(Flashcards, JSON·Markdown·HTML), 보고서(Briefing doc, study guide, blog post 등 Markdown), 데이터 테이블(Data Table, 자연어 명세 기반 CSV), 마인드맵(Mind Map, JSON), 인포그래픽(Infographic, PNG) 까지 다양한 산출물을 일관된 API 로 생성할 수 있습니다.
특히 흥미로운 부분은 NotebookLM 웹 UI 에서는 제공하지 않지만 API/CLI 만 노출하는 "Beyond the Web UI" 기능들입니다. 동일 유형의 모든 산출물을 한 번에 내려받는 일괄 다운로드(batch download), 퀴즈와 플래시카드를 구조화된 JSON/Markdown/HTML 형태로 내보내는 export, 마인드맵을 외부 시각화 도구에서 쓰기 위한 계층형 JSON 추출, 데이터 테이블을 CSV 로 내려받기, 슬라이드 덱을 편집 가능한 PPTX 로 받기, 슬라이드 단위로 자연어 프롬프트(prompt) 를 사용한 수정, 보고서 템플릿에 추가 지시문 덧붙이기, 채팅 답변을 노트북 노트로 저장하기, 소스의 색인된 전체 텍스트를 가져오기, 공유 권한을 프로그램으로 관리하기, 여러 Google 계정 프로필을 전환하기, 기존 브라우저 쿠키를 그대로 들고 와 인증 부담을 줄이기 등이 여기에 해당합니다.
notebooklm-py 의 세 가지 사용 방식
notebooklm-py 는 같은 기능 집합을 세 가지 인터페이스로 제공하기 때문에 사용 맥락에 따라 가장 자연스러운 방식을 고를 수 있습니다. Python API 는 애플리케이션 임베드(embed), 비동기 워크플로우, 사용자 정의 파이프라인에 적합하고, CLI 는 셸 스크립트와 빠른 작업, CI/CD 자동화에 유용하며, Agent 통합 방식은 Claude Code 와 Codex, 그리고 OpenClaw 와 같은 LLM 기반 에이전트가 자연어 명령으로 NotebookLM 을 다루도록 만들어 줍니다. 같은 RPC 호출이 세 인터페이스에서 동일하게 노출되므로, 인터페이스 간 결과 차이가 적고 한 번 배운 멘탈 모델을 그대로 옮겨 쓸 수 있습니다.
CLI 사용은 다음과 같이 인증 후 노트북 생성, 소스 추가, 채팅, 산출물 생성 및 다운로드의 흐름으로 이어집니다. 긴 프롬프트는 --prompt-file 옵션으로 파일에서 읽도록 분리할 수 있어 셸 명령행 길이 제한도 피할 수 있습니다.
# 1. 인증 (브라우저 창이 열립니다)
notebooklm login
# 2. 노트북 생성과 소스 추가
notebooklm create "My Research"
notebooklm use <notebook_id>
notebooklm source add "https://en.wikipedia.org/wiki/Artificial_intelligence"
notebooklm source add "./paper.pdf"
# 3. 소스 기반 질의
notebooklm ask "What are the key themes?"
# 4. 산출물 생성
notebooklm generate audio "make it engaging" --wait
notebooklm generate video --style whiteboard --wait
notebooklm generate quiz --difficulty hard
notebooklm generate mind-map
# 5. 산출물 다운로드
notebooklm download audio ./podcast.mp3
notebooklm download mind-map ./mindmap.json
Python API 는 비동기 컨텍스트 매니저(async context manager) 형태로 사용하며, 한 번 만든 NotebookLMClient 안에서 notebooks, sources, chat, artifacts 와 같은 도메인별 네임스페이스(namespace) 를 통해 자연스럽게 호출할 수 있습니다.
import asyncio
from notebooklm import NotebookLMClient
async def main():
async with await NotebookLMClient.from_storage() as client:
# 노트북 생성 및 소스 추가
nb = await client.notebooks.create("Research")
await client.sources.add_url(nb.id, "https://example.com", wait=True)
# 소스 기반 질의응답
result = await client.chat.ask(nb.id, "Summarize this")
print(result.answer)
# 오디오 개요 생성 및 다운로드
status = await client.artifacts.generate_audio(nb.id, instructions="make it fun")
await client.artifacts.wait_for_completion(nb.id, status.task_id)
await client.artifacts.download_audio(nb.id, "podcast.mp3")
# 퀴즈 생성 및 JSON 저장
status = await client.artifacts.generate_quiz(nb.id)
await client.artifacts.wait_for_completion(nb.id, status.task_id)
await client.artifacts.download_quiz(nb.id, "quiz.json", output_format="json")
asyncio.run(main())
Agent 통합은 가장 차별화된 기능입니다. CLI 에 내장된 notebooklm skill install 명령은 ~/.claude/skills/notebooklm 과 ~/.agents/skills/notebooklm 두 위치에 SKILL.md 를 설치하고, npx skills add teng-lin/notebooklm-py 명령으로는 GitHub 에서 동일 스킬을 가져옵니다. Claude Code, Codex, 그리고 같은 인터페이스를 따르는 다른 LLM 에이전트가 자연어 지시를 받았을 때 이 스킬 문서를 읽고 CLI/Python API 를 호출해 노트북 생성, 소스 일괄 추가, 오디오/영상 개요 생성, 산출물 다운로드까지 한 번에 수행하도록 만드는 것이 목표입니다.
notebooklm-py 의 설치와 인증 흐름
notebooklm-py 는 사용 목적에 따라 두 가지 설치 프로파일을 권장합니다. CLI 사용자와 AI 에이전트에게는 Playwright 와 함께 설치하는 풀(full) 모드가 적합합니다.
pip install "notebooklm-py[browser]" # core + Playwright
playwright install chromium # 약 170 MB, 진행률 표시 없이 30~90초 소요
notebooklm login # 구글 로그인용 브라우저 창이 열립니다
notebooklm auth check --test --json # status: "ok" 가 나오면 인증 완료
반면 본인이 만든 다른 애플리케이션에 NotebookLM 기능을 임베드(embed) 하고 싶을 때는, Chromium 을 동봉하지 않는 약 10 MB 크기의 라이브러리만 설치하고 다른 환경에서 미리 발급한 storage_state.json 을 함께 배포하는 라이브러리 모드를 사용하면 됩니다.
pip install notebooklm-py
인증 측면에서는 한 번 로그인한 뒤에도 시간이 지나면 쿠키가 만료될 수 있으므로 notebooklm auth refresh --quiet 명령이 cron 이나 launchd, systemd 에 등록할 수 있는 일회성 쿠키 갱신용으로 제공됩니다. 회사 계정(SSO) 처럼 Microsoft Edge 가 필요한 환경을 위해 notebooklm login --browser msedge 도 지원하며, 여러 Google 계정을 동시에 쓰는 경우 notebooklm profile list 및 notebooklm profile switch <name> 으로 활성 프로필을 전환할 수 있습니다. 자세한 6가지 페르소나별 설치 가이드(agent, end-user, library, headless, contributor, power-user) 와 선택적 extras 매트릭스는 저장소의 docs/installation.md 에 정리되어 있습니다.
라이선스
notebooklm-py 는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용·수정·재배포할 수 있습니다. 다만 NotebookLM 자체의 이용 약관은 Google 이 별도로 관리하므로, 자동화된 호출이 NotebookLM 의 사용 정책과 속도 제한(rate limit) 을 위반하지 않도록 주의가 필요합니다.
notebooklm-py 공식 홈페이지
notebooklm-py 문서 사이트
notebooklm-py 프로젝트 GitHub 저장소
더 읽어보기
-
NotebookLM MCP: AI 에이전트가 NotebookLM을 통해 문서를 직접 검색하고 인용 근거 기반으로 답변하는 MCP 서버
-
Google의 NotebookLM, 기존 Audio / Mindmap 생성에 더해 Video 개요 생성 기능 출시
-
Agent Skills: 소프트웨어 개발 생명주기 전체를 커버하는 AI 코딩 에이전트용 프로덕션급 20개 엔지니어링 스킬 모음
이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. 
파이토치 한국 사용자 모임
이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일
로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)
아래
쪽에 좋아요
를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ 