Skip to main content
Glama
notebooklm-mcp-pro

notebooklm-mcp-pro

by SantosRojas

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.json que crea notebooklm login es 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

notebooklm-mcp incluido

Enfoque

Acceso al conocimiento para agentes de código

Automatización integral de NotebookLM

Lectura económica en contexto

get_source_outline, read_source_section, paginación por next_offset

—

Búsqueda local sin cuota

keyword_search (BM25) y grep (texto/regex con contexto), en una notebook o en todas a la vez

—

Exportar fuentes a .md en disco

export_markdown (notebook completo o una fuente, en la carpeta que elijas)

—

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

health_check

Modo, caché, versiones, antigüedad de la sesión (avisa cuando toca reloguear) y file_upload_hint (cómo habilitar la subida si está apagada)

list_notebooks, get_notebook

Notebooks, resumen generado y temas sugeridos

list_sources

Fuentes con tipo, estado, URL y nº de palabras (filtrable; limit opcional)

read_source

Fuente en Markdown, paginada (offset → next_offset)

get_source_outline

Índice de encabezados (ignora # dentro de bloques de código)

read_source_section

Solo una sección, hasta el siguiente encabezado del mismo nivel

get_source_guide

Resumen y palabras clave que NotebookLM genera por fuente

search_sources

Búsqueda semántica de NotebookLM (fragmentos por relevancia)

keyword_search

Búsqueda léxica BM25 local (sin acentos/mayúsculas)

grep

Texto o regex con líneas de contexto, sobre la caché

source_stats

Radiografía local sin cuota: por fuente (caracteres, palabras, encabezados, términos dominantes) o, sin notebook_id, resumen de toda la caché (fuentes, caracteres, antigüedad)

ask_notebook

Pregunta con respuesta y citas a las fuentes (ver nota); si NotebookLM cierra con una oferta de Studio, va en suggestions y no ensucia answer

list_notes, read_note

Notas del notebook

list_artifacts, read_report, get_generation_status

Informes y su estado: read_report lee los de tipo report (los de generate_report), get_generation_status acepta wait_seconds y espera el estado terminal

get_usage

Cuota de la cuenta (ventanas y acciones con capacidad restante). Si la cuenta no la expone, responde status: disabled

get_chat_history

Historial de chat del notebook (turnos pregunta/respuesta)

sync_notebook

Descarga todas las fuentes a la caché local

export_markdown

Deja un .md por fuente (con front matter) + INDEX.md en disco; incremental (reescribe solo lo que cambió). Con source_id exporta una sola fuente, y directory elige la carpeta destino

clear_cache

Borra caché y exportaciones locales de un notebook — o de TODOS con purge_all: true

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

  1. list_notebooks → list_sources para ubicar el material.

  2. Localizar: search_sources (semántica) o keyword_search / grep (local). Si no sabes en qué notebook está algo, omite notebook_id (notebook_ids para limitar el barrido): ambas recorren todas las notebooks y etiquetan cada resultado con su origen.

  3. Leer: get_source_outline → read_source_section. read_source solo si hace falta el documento entero. source_stats resume tamaño, encabezados y términos dominantes sin gastar cuota (sin notebook_id, toda la caché: útil para decidir sync_notebook o clear_cache).

  4. ask_notebook cuando se quiere una síntesis con citas ya hecha por NotebookLM.

  5. export_markdown si el agente va a trabajar con sus herramientas de archivos (directory para dejar los .md donde 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

NLM_MCP_MODE

readonly

readonly o readwrite

NLM_MCP_ALLOW_DESTRUCTIVE

0

Habilita borrado (solo con readwrite)

NLM_UPLOAD_DIRS

(vacío)

Carpetas permitidas para add_source_file y add_source_base64 (separador : en Linux/Mac, ; en Windows). Vacío = subida deshabilitada

NLM_STORAGE_PATH

(de la librería)

Ruta a storage_state.json

NLM_PROFILE

(activo)

Perfil de notebooklm-py (varias cuentas)

NLM_CACHE_DIR

~/.cache/notebooklm-mcp-pro

Caché, exportaciones y auditoría

NLM_CACHE_TTL_SECONDS

3600

Vigencia de la caché (0 = nunca usarla)

NLM_MAX_CHARS

20000

Tamaño máximo de página devuelta al agente (mín. 1000)

NLM_MAX_CONCURRENCY

4

Llamadas simultáneas a NotebookLM

NLM_TIMEOUT_SECONDS

60

Timeout por llamada (algunas operaciones lo multiplican)

NLM_DEFAULT_LANGUAGE

es

Idioma por defecto de generate_report

NLM_AUDIT_LOG

<cache>/audit.jsonl

Registro de escrituras/borrados

NLM_AUDIT_MAX_BYTES

10485760

Rotación del registro de auditoría por tamaño (se guarda una generación en .1)

NLM_RETRIES

2

Reintentos (0-5) ante errores de red/servidor/cuota en lecturas; las operaciones no idempotentes nunca se reintentan

NLM_LOG_JSON

0

1 = logs en JSON estructurado en stderr (una línea por evento)

NLM_STRIP_IMAGES

1

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

NLM_LOG_LEVEL

INFO

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 readonly las 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: true y 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, archivos 0600, 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: stdio por defecto. --transport streamable-http solo enlaza a loopback; --allow-remote existe pero no hay autenticación: expondría tu sesión de Google. No lo uses sin un proxy con autenticación.

  • grep es literal por defecto; con literal=false usa 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 devuelve timed_out: true, aunque una única línea con backtracking catastrófico puede seguir demorando).

  • export_markdown con directory escribe donde le pidas (absoluto, o relativo a la carpeta de exportaciones del servidor): es una escritura local a cargo del agente, como el resto de readonly.

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 JSONL

Todo 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 mypy

111 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

auth: error / «No hay sesión»

Ejecuta notebooklm login o define NLM_STORAGE_PATH

Sesión caducada

Repite notebooklm login y reinicia el cliente MCP

«Google aplicó un límite»

Baja NLM_MAX_CONCURRENCY y espera unos minutos

read_source devuelve poco

Es una página: sigue con next_offset o usa read_source_section

Una fuente no aparece en búsquedas locales

Solo se descargan fuentes en estado ready; revisa list_sources

read_report dice que el artefacto «no es un informe»

Es un archivo, audio o presentación: solo los de tipo report tienen texto. Para fuentes usa export_markdown; para notas, read_note

get_usage devuelve status: disabled

La API interna de cuota no está habilitada para esa cuenta; el resto de herramientas funciona igual

add_source_file / add_source_base64 dice «deshabilitada»

Define NLM_UPLOAD_DIRS (lo mismo anuncia health_check.file_upload_hint) y reinicia el cliente MCP

text_density_warning en una subida

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 notebooklm-py

API no oficial: mantén la versión fijada o ajusta backend.py

Available Tools

23 tools
ask_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_cacheA
Idempotent

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_markdownA
Idempotent

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_historyA
Read-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_statusA
Read-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_notebookC
Read-onlyIdempotent

Metadatos de un notebook, su resumen generado y temas sugeridos.

Inputs: notebook_id (required). Returns: object

get_source_guideC
Read-onlyIdempotent

Resumen y palabras clave que NotebookLM genera para una fuente.

Inputs: source_id (required), notebook_id (required). Returns: object

get_source_outlineB
Read-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_usageA
Read-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

grepA
Idempotent

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_checkB
Read-onlyIdempotent

Estado del servidor y de la sesión con NotebookLM (modo, caché, autenticación).

Inputs: no named parameters. Returns: object

list_artifactsA
Read-onlyIdempotent

Lista los artefactos generados (informes, audio, cuestionarios, mapas mentales...) y su estado.

Inputs: notebook_id (required). Returns: object

list_notebooksB
Read-onlyIdempotent

Lista los notebooks de la cuenta (id, título, nº de fuentes, fechas).

Inputs: limit, query. Returns: object

list_notesB
Read-onlyIdempotent

Lista las notas del notebook con una vista previa.

Inputs: notebook_id (required). Returns: object

list_sourcesB
Read-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_noteB
Read-onlyIdempotent

Lee una nota completa (paginada).

Inputs: note_id (required), notebook_id (required), offset, max_chars. Returns: object

read_reportA
Read-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_sourceA
Read-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_sectionB
Read-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_sourcesB
Read-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_statsA
Idempotent

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_notebookA
Idempotent

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

    B3.4/5.0

    Scored across 23 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness3/5

    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

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Enables 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.
      28
      59 PyPI
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Gives 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
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      2
      Apache 2.0