perplexity-notebooklm 0.5.0

Integração dual NotebookLM <-> Perplexity (conta Pro, sem API key) via MCP + skill

English · Português 🇧🇷

The missing bridge between Perplexity's web intelligence and NotebookLM's knowledge base — driven by Claude Code, with zero paid API keys.

---

Why this exists

You research on Perplexity. You build knowledge on NotebookLM. Today they don't talk — you copy-paste between tabs, lose citations, and re-research the same topics.

This project closes the loop. It's the only tool that wires Perplexity and NotebookLM both ways, using your Pro accounts (cookies) instead of paid API keys — so it costs you nothing beyond subscriptions you already pay for.

flowchart LR
    subgraph PPLX["🔎 Perplexity Pro"]
        S[search / reason / deep research<br/>+ citations]
    end
    subgraph NLM["📓 NotebookLM"]
        N[sources · summaries · audio/video/mind-map]
    end
    S -- "research → source (verified, deduped)" --> N
    N -- "summary → enrich / fact-check" --> S
    C[/"Claude Code<br/>orchestrator"/] -.drives.- S
    C -.drives.- N

---

What you get

	Capability
🔁	Bidirectional dual flow — research → notebook source, and notebook → enriched research. Nobody else does both.
🔑	No paid API keys — Perplexity via account cookies; NotebookLM via a one-time cookie-bridge.
📎	Citations preserved — replicates the SSE recipe that surfaces real web sources.
🧹	4-layer dedup — never ingest the same thing twice (query → exact → near-verbatim → semantic embeddings, all local).
🛡️	Adversarial citation verification — drops hallucinated/dead sources before they reach your notebook.
🤖	Agentic deep-research — decomposes a question, searches each angle, synthesizes a cited report.
🎧	Media pipeline — turn research into a NotebookLM audio overview, video, or mind-map in one call.
👁️	Continuous watcher — monitors notebooks for real changes (stable source-id signal) with hard ToS guards.
🔌	Ships as a Claude Code plugin — /dual-research, /notebook-enrich, MCP server, session hook.

---

Quickstart

Prereqs: uv on PATH + Python 3.12/3.13 (not 3.14). uv handles the venv & deps. Full guide: docs/INSTALL.md.

# 1. Install as a Claude Code plugin (brings MCP + commands + skill + hook).
#    uv run auto-creates the venv on first launch — cross-OS, no hardcoded paths.
/plugin marketplace add wgardim-hub/notebooklm2perplexity
/plugin install perplexity-notebooklm@perplexity-notebooklm-dev   # restart Claude Code

# 2. Guided login (pulls cookies from a logged-in Chrome — no manual paste).
#    Open once: chrome --remote-debugging-port=9222 --user-data-dir="<profile>"
#    logged into perplexity.ai AND NotebookLM, then:
uv run --directory <repo> perplexity-nlm-auth

# 3. Verify everything ("did I configure it right?")
uv run --directory <repo> perplexity-nlm-doctor

One canonical path. Don't also copy the skill into ~/.claude/skills/ — the plugin ships it. The package is self-contained (no vendored deps) — once published to PyPI, the MCP runs via uvx perplexity-notebooklm. Manual install & python -m perplexity_mcp.server: see docs/INSTALL.md.

---

The two flows

from dual_flow import research_to_notebook, notebook_to_research, research_to_media

# Perplexity → NotebookLM  (research becomes a verified, deduped source)
research_to_notebook("State of commercial fusion in 2026", NB, tool="research",
                     verify=True, dedup=True)

# NotebookLM → Perplexity  (read the notebook, fact-check & update against the live web)
notebook_to_research(NB, tool="search")

# Research → media  (source + audio / video / mind-map in one call)
research_to_media("AI in real estate 2026", NB, kind="mind_map")

NotebookLM auth: Google blocks automated logins, so the first run needs a real Chrome you control: chrome.exe --remote-debugging-port=9222 --user-data-dir="D:\nlm-chrome" (log in once). After that it's pure HTTP with automatic cookie re-bridge.

---

Architecture

perplexity_mcp/      MCP server · pluggable backend (helallao) · cited_search
                     resilience (retry/jitter/rate-limit) · security · validate
                     verify_citations (adversarial) · agentic (deep-research)
notebooklm_write/    nlm_http (notebooklm-py HTTP/RPC + cookie-bridge) · add_source (Selenium fallback)
                     ledger (4-layer dedup) · embed (local model2vec)
dual_flow.py         the bidirectional orchestration
rag.py · watch.py    cross-notebook BM25 retrieval · change watcher
evals/ · skills/     regression harness · Claude Code skill
.claude-plugin/      plugin manifest · commands · hooks

Design principles: small, single-purpose modules · pluggable Perplexity backend (swap providers without touching callers) · graceful degradation everywhere (no Chrome → clean error; no embedder → falls back to MinHash; stale cookie → auto re-bridge) · eval harness as a regression gate · honest about limits.

Dedup, in 4 layers (cheapest first)

Layer	Catches	Cost
Query	re-researching the same topic	free (skips before the Pro call)
Exact hash	identical content	free
MinHash	near-verbatim edits	free
Semantic	reworded / paraphrased (cosine ≈ 0.90)	local embedding, no API

---

Reliability & safety

• Resilience: exponential backoff + full jitter, rate limiting, single-flight auth refresh.
• Your accounts, your cookies: every user authenticates with their own Perplexity/NotebookLM. Credentials live only in your local .env + ~/.notebooklm/ (git-ignored, never committed, never shipped in the package). Nothing personal is bundled — a fresh install has zero cookies; you run perplexity-nlm-auth to pull your own.
• Security: secrets only in .env (git-ignored); cookie values never logged (redaction); file perms hardened.
• ToS-aware automation: the watcher defaults to dry-run, enforces a ≥10-min poll floor, an interruptible kill-switch, and writes only through an explicit callback with a human checkpoint.
• Tested: eval harness (evals/run.py) + end-to-end validation on real accounts (dual flow, 44-notebook RAG, dedup, watcher).

---

Honest limitations

A senior project says what it doesn't do:

• Built on unofficial Perplexity/NotebookLM interfaces — they can change; expect occasional maintenance.
• Continuous automation against your accounts carries inherent ToS risk — use sparingly.
• Semantic dedup needs the optional local model; without it, dedup falls back to lexical.
• NotebookLM write/read needs a logged-in Chrome on the debug port (Google blocks headless login).

---

Roadmap

See docs/INNOVATION.md for the full ranked roadmap, and docs/BENCHMARK.md for how this compares against 7 ecosystem projects.

License

MIT — see LICENSE. Not affiliated with Perplexity AI or Google.