notebooklm-mcp-pro
Integrates with Google NotebookLM (Gemini Notebook) to let agents list notebooks and sources, read and search source Markdown, query notebooks with citations, export sources to local Markdown files, and optionally manage notes, sources, reports, and notebooks using a Google account session.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@notebooklm-mcp-pro search all my notebooks for anything about rate limiting"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
notebooklm-mcp-pro
Servidor MCP para NotebookLM (ahora «Gemini Notebook») pensado para que un agente de código lea, busque y razone sobre los documentos de tu cuenta gastando el mínimo de contexto, y que solo pueda escribir o borrar si tú lo habilitas expresamente.
Aprovecha que NotebookLM ya guarda cada fuente convertida a Markdown: el agente puede ver el
índice de encabezados, leer solo la sección que necesita, buscar en local (BM25 / grep) sin gastar
cuota, o exportar todo a una carpeta de .md para trabajar con sus propias herramientas de archivos.
⚠️ API no oficial. NotebookLM no tiene API pública para cuentas personales. Este proyecto usa
notebooklm-py, que emplea endpoints internos de Google y puede romperse sin aviso (por eso la versión está fijada a>=0.8.5,<0.9). Úsalo con tu propia cuenta y bajo tu responsabilidad; revisa los términos de servicio de Google.🔐 El
storage_state.jsonque creanotebooklm logines tu sesión de Google. Trátalo como una contraseña: no lo subas a Git ni lo compartas.
¿En qué se diferencia del MCP que ya trae notebooklm-py?
notebooklm-py incluye su propio servidor (notebooklm-mcp), amplio en administración: compartir
notebooks, investigación web/Drive, generación de audio/vídeo, OAuth para alojarlo en remoto, etc.
Este proyecto no lo reemplaza; se centra en otra cosa:
Este proyecto |
| |
Enfoque | Acceso al conocimiento para agentes de código | Automatización integral de NotebookLM |
Lectura económica en contexto |
| — |
Búsqueda local sin cuota |
| — |
Exportar fuentes a |
| — |
Seguridad | Solo lectura por defecto; las herramientas de escritura ni se registran si no se habilitan; borrado exige repetir el título exacto; auditoría | Confirmaciones vía anotaciones MCP |
No cubre | Compartir, investigación web/Drive, audio/vídeo/cuestionarios, OAuth remoto | — |
Si necesitas lo que aquí no está, puedes ejecutar ambos servidores a la vez.
Related MCP server: karpathy-mcp
Instalación
Requiere Python ≥ 3.10.
cd notebooklm-mcp-pro
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e ".[browser]" # incluye Playwright, necesario solo para el login
playwright install chromium # si el login pide el navegador de Playwright
notebooklm login # abre el navegador y guarda la sesión (storage_state.json)
notebooklm-mcp-pro --check # verifica configuración y sesión--check imprime un JSON de estado y devuelve código 0 si la sesión es válida (auth: ok).
Conectarlo a opencode
Añade esto a ~/.config/opencode/opencode.json (o al opencode.json del proyecto), con la ruta real
(examples/opencode.json tiene el archivo listo para copiar):
{
"mcp": {
"servers": {
"notebooklm": {
"type": "local",
"command": ["/RUTA/ABSOLUTA/notebooklm-mcp-pro/.venv/bin/notebooklm-mcp-pro"],
"environment": { "NLM_MCP_MODE": "readonly" }
}
}
}
}En Windows el ejecutable está en .venv\Scripts\notebooklm-mcp-pro.exe. Para Claude Desktop y otros
clientes con la clave mcpServers, usa examples/claude_desktop_config.json.
Esta es la forma nativa de OpenCode 2: los servidores van bajo mcp.servers y para dejar uno
configurado sin conectar se usa disabled: true. En OpenCode 1 el nombre va directamente bajo mcp y
el campo equivalente es enabled (su inverso); V2 sigue aceptando esa forma, pero conviene migrarla.
Herramientas
Siempre disponibles (modo readonly) — 23
Herramienta | Para qué sirve |
| Modo, caché, versiones, antigüedad de la sesión (avisa cuando toca reloguear) y |
| Notebooks, resumen generado y temas sugeridos |
| Fuentes con tipo, estado, URL y nº de palabras (filtrable; |
| Fuente en Markdown, paginada ( |
| Índice de encabezados (ignora |
| Solo una sección, hasta el siguiente encabezado del mismo nivel |
| Resumen y palabras clave que NotebookLM genera por fuente |
| Búsqueda semántica de NotebookLM (fragmentos por relevancia) |
| Búsqueda léxica BM25 local (sin acentos/mayúsculas) |
| Texto o regex con líneas de contexto, sobre la caché |
| Radiografía local sin cuota: por fuente (caracteres, palabras, encabezados, términos dominantes) o, sin |
| Pregunta con respuesta y citas a las fuentes (ver nota); si NotebookLM cierra con una oferta de Studio, va en |
| Notas del notebook |
| Informes y su estado: |
| Cuota de la cuenta (ventanas y acciones con capacidad restante). Si la cuenta no la expone, responde |
| Historial de chat del notebook (turnos pregunta/respuesta) |
| Descarga todas las fuentes a la caché local |
| Deja un |
| Borra caché y exportaciones locales de un notebook — o de TODOS con |
Convenciones de las respuestas: count es lo que devuelve la llamada y total lo que coincide antes del
recorte; los listados con limit añaden truncated y las lecturas paginadas next_offset. Lo que sale
del contenido de las fuentes va marcado con untrusted_content: true (texto de terceros: nunca
instrucciones). Las herramientas de barrido añaden notebooks_requested, notebooks_scanned (y
notebooks_scanned_ids: con max_notebooks conviene comprobar que tu notebook entró en el tope),
sources_not_ready, download_errors (por fuente) y notebook_errors (por notebook). Las subidas
(add_source_file, add_source_base64) añaden text_density_warning solo cuando el archivo trae
muy poco texto para su tamaño — típicamente un deck de imágenes que NotebookLM no podrá cubrir del todo.
Tres detalles del contrato que son deliberados: en un barrido, notebook_title solo se rellena cuando se
recorren varias notebooks (en una sola ya sabes cuál es y se ahorra una llamada); las búsquedas no
devuelven total porque el escaneo se corta al agotar el presupuesto y un total sería un dato falso
(truncated avisa de que había más); y grep/keyword_search son locales, así que no consumen cuota.
También expone el recurso notebooklm://notebooks, la plantilla
notebooklm://notebooks/{notebook_id}/sources/{source_id} y tres prompts
(research_topic, summarize_source, compare_sources).
Nota sobre
ask_notebook: no modifica fuentes, por eso está en modo lectura, pero consume la cuota de chat de tu cuenta y deja la pregunta en el historial del notebook.
Con NLM_MCP_MODE=readwrite — +10
create_notebook, rename_notebook, add_source_url (solo http/https), add_source_text,
add_source_file (solo desde carpetas de NLM_UPLOAD_DIRS), add_source_base64 (bytes ya en
memoria, p. ej. un adjunto de correo: pasan por un temporal efímero dentro de NLM_UPLOAD_DIRS y no
viajan por el contexto del agente), rename_source, create_note, update_note, generate_report
(asíncrona: luego get_generation_status y read_report).
Con readwrite + NLM_MCP_ALLOW_DESTRUCTIVE=1 — +4
delete_source, delete_note, delete_artifact y delete_notebook: exigen confirm_title con el
título exacto actual. Si no coincide, no se borra nada y el error no revela el título correcto,
así el agente tiene que consultarlo (y tú confirmarlo) en lugar de reintentar a ciegas.
Flujo recomendado para el agente
list_notebooks→list_sourcespara ubicar el material.Localizar:
search_sources(semántica) okeyword_search/grep(local). Si no sabes en qué notebook está algo, omitenotebook_id(notebook_idspara limitar el barrido): ambas recorren todas las notebooks y etiquetan cada resultado con su origen.Leer:
get_source_outline→read_source_section.read_sourcesolo si hace falta el documento entero.source_statsresume tamaño, encabezados y términos dominantes sin gastar cuota (sinnotebook_id, toda la caché: útil para decidirsync_notebookoclear_cache).ask_notebookcuando se quiere una síntesis con citas ya hecha por NotebookLM.export_markdownsi el agente va a trabajar con sus herramientas de archivos (directorypara dejar los.mddonde te interese).
La primera keyword_search/grep de un notebook descarga sus fuentes (campo downloaded_now);
después usan la caché. Con auto_sync=false buscan solo en lo ya descargado.
Configuración (variables de entorno o .env)
Variable | Defecto | Descripción |
|
|
|
|
| Habilita borrado (solo con |
| (vacío) | Carpetas permitidas para |
| (de la librería) | Ruta a |
| (activo) | Perfil de |
|
| Caché, exportaciones y auditoría |
|
| Vigencia de la caché ( |
|
| Tamaño máximo de página devuelta al agente (mín. 1000) |
|
| Llamadas simultáneas a NotebookLM |
|
| Timeout por llamada (algunas operaciones lo multiplican) |
|
| Idioma por defecto de |
|
| Registro de escrituras/borrados |
|
| Rotación del registro de auditoría por tamaño (se guarda una generación en |
|
| Reintentos (0-5) ante errores de red/servidor/cuota en lecturas; las operaciones no idempotentes nunca se reintentan |
|
|
|
|
| Recorta imágenes incrustadas (base64) del Markdown de las fuentes: los PDFs con screenshots vienen con MB de blobs; por defecto se reemplazan por marcadores de texto |
|
| Los logs van a stderr (stdout es del protocolo) |
Hay una plantilla en .env.example. El servidor lee ./.env si existe (sin pisar variables ya definidas).
Modelo de seguridad
Mínimo privilegio: en
readonlylas herramientas de escritura no existen para el agente.Borrado deliberado: doble habilitación (
readwrite+ flag) y título exacto como confirmación.Contenido no confiable: el texto de las fuentes se marca con
untrusted_content: truey las instrucciones del servidor piden tratarlo como datos, no como órdenes (mitiga prompt injection).IDs validados (
[A-Za-z0-9_-]): imposible escapar de la carpeta de caché con../.Subidas solo desde carpetas permitidas; se resuelven symlinks y
..antes de comprobar.Sin filtración de errores: al agente solo llegan mensajes controlados (nunca cookies, rutas ni trazas). Cada fallo lleva un
ref(p. ej.... (ref 3a9c1f2b)) que aparece en los logs de stderr para que el operador pueda encontrar la traza exacta.Caché privada: directorios
0700, archivos0600, escritura atómica. Nota: los permisos POSIX se aplican en Linux/Mac; en Windows se ignora silenciosamente (protege la ruta con tu perfil).Auditoría JSONL de toda escritura/borrado; nunca guarda contenido, solo longitud y huella SHA-256.
Transporte:
stdiopor defecto.--transport streamable-httpsolo enlaza a loopback;--allow-remoteexiste pero no hay autenticación: expondría tu sesión de Google. No lo uses sin un proxy con autenticación.grepes literal por defecto; conliteral=falseusa regex de Python (limitada a 300 caracteres y con un presupuesto de ~5 s de escaneo: si la regex es patológica, se corta y devuelvetimed_out: true, aunque una única línea con backtracking catastrófico puede seguir demorando).export_markdowncondirectoryescribe donde le pidas (absoluto, o relativo a la carpeta de exportaciones del servidor): es una escritura local a cargo del agente, como el resto dereadonly.
Arquitectura
src/nlm_mcp/
server.py herramientas, recursos y prompts (registro condicionado por modo)
backend.py Protocol `Backend` + adaptador sobre notebooklm-py (único archivo que toca la librería;
lecturas idempotentes con reintento y backoff ante red/5xx/cuota)
state.py concurrencia, timeouts, descarga única por fuente, sincronización
cache.py caché Markdown en disco (TTL, atómica, privada)
mdtools.py outline, secciones, paginación, grep, troceado
bm25.py búsqueda léxica local
validators.py IDs, rutas de subida, regex
errors.py excepciones de la librería -> mensajes accionables
config.py configuración validada (inmutable)
audit.py auditoría JSONLTodo el servidor depende de la interfaz Backend, no de notebooklm-py. Si Google rompe algo o quieres
otro origen de datos, solo se toca backend.py.
Pruebas
uv sync --extra dev # o: pip install -e ".[dev]"
uv run --extra dev pytest
uv run --extra dev ruff check .
uv run --extra dev ruff format --check .
uv run --extra dev mypy111 pruebas: unitarias (config, validadores, Markdown, BM25, caché), de servidor completo con un cliente MCP
en memoria (modos, gating de seguridad, paginación, búsqueda local en una o varias notebooks, grep con
contexto, exportación incremental y a una carpeta elegida, errores, escritura, borrado, recursos, prompts,
CLI, generaciones con y sin espera, cuota e historial) y del adaptador
contra los modelos reales de notebooklm-py (incluidos los reintentos ante errores transitorios).
ruff check, ruff format --check y mypy (configuración laxa, solo src/) y las pruebas corren en CI en cada push
(GitHub Actions, .github/workflows/ci.yml).
Estado de verificación: las pruebas no se ejecutan contra Google (requieren una cuenta real).
El adaptador se validó con instancias reales de las clases de la librería y un cliente simulado; la
primera ejecución real con tu cuenta puede revelar diferencias. Empieza con notebooklm-mcp-pro --check
y una lectura sobre un notebook de prueba.
Solución de problemas
Síntoma | Causa y solución |
| Ejecuta |
Sesión caducada | Repite |
«Google aplicó un límite» | Baja |
| Es una página: sigue con |
Una fuente no aparece en búsquedas locales | Solo se descargan fuentes en estado |
| Es un archivo, audio o presentación: solo los de tipo |
| La API interna de cuota no está habilitada para esa cuenta; el resto de herramientas funciona igual |
| Define |
| Pocas palabras para el tamaño: el material es de imágenes/escaneado y puede quedar sin cubrir. Añade una fuente de texto complementaria |
Falla tras actualizar | API no oficial: mantén la versión fijada o ajusta |
Available Tools
23 toolsask_notebookA
Pregunta al notebook y devuelve respuesta con citas a fuentes. Consume cuota de chat y queda en el historial del notebook.
Inputs: question (required), notebook_id (required), source_ids, conversation_id. Returns: object
clear_cacheAIdempotent
Borra la caché local y las exportaciones (no toca nada en NotebookLM).
purge_all=True vacía por completo el estado local (útil antes de un refresco
masivo); en ese caso no se requiere notebook_id.
Inputs: purge_all, notebook_id. Returns: object
export_markdownAIdempotent
Exporta a .md (con front matter) un notebook completo o una sola fuente.
Notebook completo (incremental): solo reescribe las fuentes cuyo Markdown cambió —el resto
conserva su exported_at—, deja INDEX.md + .manifest.json y borra los .md de fuentes
que ya no existen (force reescribe todo). Una sola fuente: escribe ese documento y, con
refresh, lo vuelve a descargar antes. directory elige el destino; los archivos quedan
listos para las herramientas de archivos del agente.
Inputs: notebook_id (required), force, refresh, directory, +1 more. Returns: object
get_chat_historyARead-onlyIdempotent
Historial de chat del notebook: turnos (pregunta, respuesta) más recientes.
Los turnos vienen recortados y sin conversation_id: para repreguntar con contexto, usa el que devolvió ask_notebook.
Inputs: notebook_id (required), limit. Returns: object
get_generation_statusARead-onlyIdempotent
Estado de una generación iniciada con generate_report (pending / in_progress / completed / failed).
Con wait_seconds > 0 espera activamente hasta el estado terminal (o agotar la espera) y
devuelve final, para que el agente no tenga que consultar en bucle. Con 0 responde ya.
Inputs: task_id (required), notebook_id (required), wait_seconds, poll_interval_seconds. Returns: object
get_notebookCRead-onlyIdempotent
Metadatos de un notebook, su resumen generado y temas sugeridos.
Inputs: notebook_id (required). Returns: object
get_source_guideCRead-onlyIdempotent
Resumen y palabras clave que NotebookLM genera para una fuente.
Inputs: source_id (required), notebook_id (required). Returns: object
get_source_outlineBRead-onlyIdempotent
Índice de encabezados (nivel, título, línea, posición) de una fuente en Markdown.
Inputs: source_id (required), notebook_id (required). Returns: object
get_usageARead-onlyIdempotent
Cuota de la cuenta (ventanas de uso y acciones con capacidad restante).
Útil antes de lotes de ask_notebook/generate_report para no chocar con límites.
No todas las cuentas exponen la cuota: si no, devuelve status: disabled y
enabled: false — en ese caso confía en los límites por defecto y no reintentes.
Inputs: no named parameters. Returns: object
grepAIdempotent
Busca un texto o regex (como grep) en la caché: en un notebook o en todas a la vez.
Devuelve línea + contexto. Sin notebook_id recorre todas las notebooks de la cuenta y
etiqueta cada coincidencia con su origen (notebooks_scanned_ids dice cuáles se recorrieron);
una notebook con problemas no aborta el barrido (notebook_errors con ref). Es literal salvo
que uses literal=false.
Inputs: pattern (required), literal, auto_sync, source_ids, +5 more. Returns: object
health_checkBRead-onlyIdempotent
Estado del servidor y de la sesión con NotebookLM (modo, caché, autenticación).
Inputs: no named parameters. Returns: object
keyword_searchAIdempotent
Búsqueda léxica BM25 local (sin cuota) en un notebook o en todas a la vez.
Sin notebook_id barre todas las notebooks (o notebook_ids) y etiqueta cada resultado con
su notebook de origen: sirve para saber en cuál documentaste algo sin recorrerlas una por una.
notebooks_scanned_ids dice cuáles se recorrieron de verdad (con max_notebooks puede que la
que te interesa se quedara fuera). Una notebook con problemas no aborta el barrido
(notebook_errors con ref).
Inputs: query (required), limit, auto_sync, source_ids, +3 more. Returns: object
list_artifactsARead-onlyIdempotent
Lista los artefactos generados (informes, audio, cuestionarios, mapas mentales...) y su estado.
Inputs: notebook_id (required). Returns: object
list_notebooksBRead-onlyIdempotent
Lista los notebooks de la cuenta (id, título, nº de fuentes, fechas).
Inputs: limit, query. Returns: object
list_notesBRead-onlyIdempotent
Lista las notas del notebook con una vista previa.
Inputs: notebook_id (required). Returns: object
list_sourcesBRead-onlyIdempotent
Lista las fuentes de un notebook con tipo, estado, URL y nº de palabras.
Inputs: notebook_id (required), limit, status, source_type. Returns: object
read_noteBRead-onlyIdempotent
Lee una nota completa (paginada).
Inputs: note_id (required), notebook_id (required), offset, max_chars. Returns: object
read_reportARead-onlyIdempotent
Lee en Markdown un informe (briefing, guía de estudio...), paginado.
Solo los informes (tipo report, los que crea generate_report): un archivo subido, un
audio o una presentación no tienen texto que leer y la llamada lo dirá con el tipo que tiene
en lugar del «no está listo» interno de NotebookLM.
Inputs: artifact_id (required), notebook_id (required), offset, max_chars. Returns: object
read_sourceARead-onlyIdempotent
Lee una fuente en Markdown, paginada. Para documentos largos prefiere get_source_outline + read_source_section.
Inputs: source_id (required), notebook_id (required), offset, refresh, +1 more. Returns: object
read_source_sectionBRead-onlyIdempotent
Lee solo una sección (hasta el siguiente encabezado del mismo nivel o superior).
Inputs: heading (required), source_id (required), notebook_id (required), offset, +2 more. Returns: object
search_sourcesBRead-onlyIdempotent
Búsqueda semántica de NotebookLM: fragmentos más relevantes ordenados por relevancia.
Inputs: query (required), notebook_id (required), limit, source_ids. Returns: object
source_statsAIdempotent
Radiografía local de las fuentes: tamaño, palabras, encabezados y términos dominantes.
Sin notebook_id resume la caché entera por notebook (fuentes, caracteres y antigüedad),
sin red ni cuota: es la vista para decidir sync_notebook o clear_cache. Con
notebook_id mide fuente a fuente; con auto_sync=False mide solo lo ya cacheado y
lista el resto en not_cached.
Inputs: terms, auto_sync, source_ids, notebook_id. Returns: object
sync_notebookAIdempotent
Descarga todas las fuentes del notebook en Markdown a la caché local (habilita keyword_search/grep sin esperas).
Inputs: notebook_id (required), force. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 23 tools
Most tools target a clearly distinct resource/action (notebooks, sources, notes, reports, cache, quota). The main risk is the search trio—search_sources (semantic), keyword_search (BM25) and grep (regex)—which overlap conceptually, though descriptions explain when to use each. read_source vs read_source_section vs get_source_outline are also related but well differentiated.
Predominantly consistent snake_case verb_noun pattern (list_notebooks, get_notebook, read_source, sync_notebook, clear_cache). A few deviations—grep (bare verb), keyword_search and source_stats (noun/adjective-noun), health_check—but they remain readable and predictable overall.
23 tools is on the heavy side of the 16-25 band for a single server. Most tools earn their place (notebook/source/note/artifact lifecycle plus a cache and quota subsystem), but the search suite and cache utilities could be consolidated to reduce surface area.
The surface is strong on reading, searching and caching, but lacks creation/management operations: no create_notebook, add_source, create_note or delete tools. Notably, generate_report is referenced by read_report and get_generation_status but is absent from the tool list, creating a dead end for artifact generation.
Maintenance
Related MCP Connectors
Markdown workspace for AI agents: read, write, organize, and share markdown documents.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Markdown notes and whiteboards your AI agent can read and write.
Open-source Obsidian for MDX - edit local docs with agent assistance
Related MCP Servers
- AlicenseBqualityBmaintenanceEnables AI agents to capture, search, relate, review, and safely update a local-first Markdown knowledge vault through typed operations such as inventory, retrieve, run_view, update, add_attachment, trash, and restore. Agents get validated access to personal notes and attachments without a generic shell or arbitrary filesystem access.2859 PyPIApache 2.0
- AlicenseNot gradedqualityBmaintenanceGives AI agents fast, read-only access to a local knowledge base of Markdown notes and other text documents via a SQLite full-text index. Enables ranked section-level search, reading whole notes or single sections, heading outlines, note listing, and link/backlink navigation without slow disk walks.Apache 2.0
- AlicenseAqualityCmaintenanceEnables agents to add project notes as sources, list them, and ask questions that come back as text with [n] markers plus numbered quotes from the source. Backends are pluggable (local BM25 by default, Gemini File Search, or notebooklm-py) behind a risk gate that filters secrets and personal data before any call leaves the machine.3Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code and Claude Desktop to search, read, and write a local-first Markdown knowledge base so users' notes act as persistent agent memory across sessions.2Apache 2.0