NotebookLM MCP with Audio (custom fork)

Repository: https://github.com/sasuketorii/notebooklm_mcp_with Release version and reviewed upstream provenance: RELEASE_PROVENANCE.json

This is a maintained custom fork of PleasePrompto/notebooklm-mcp. It keeps NotebookLM chat, web-URL/text sources, library and audio-overview tools, and adds a bounded local-audio/YouTube workflow. It is intended for local or single-principal use through Codex or Claude Code; it is not an npm package release.

このリポジトリは 上流 notebooklm-mcp のカスタムforkです。チャット、Web URL／テキストソース、ライブラリ、Audio Overviewを維持し、ローカル音声・YouTube登録、準備待ち、UI文字起こし出力を追加します。Codex／Claude Codeからのローカルまたは単一信頼主体での利用を想定し、npmパッケージとしては公開していません。

What this fork adds / このforkの目的

• add_audio_source: NotebookLMのファイル選択UIで音声を登録（外部ASRへ送信しない）。

• add_youtube_source: 公開YouTube URLをNotebookLMへ登録。

• wait_for_source_ready: ソース一覧のUI状態を安定ポーリング。

• export_transcript: ソースビューアに表示された文字列をmarkdown/jsonで保存。

• audio-root allowlist、SHA-256／サイズ receipt、入力形式・サイズ上限。

The remaining tools cover Q&A (ask_question), URL/text ingestion (add_source), Audio Overview generation/status/download, notebook library CRUD/search, session lifecycle, health, authentication, and cleanup. その他に、質問応答、URL／テキスト登録、Audio Overviewの生成・状態確認・ダウンロード、ノートブックの追加・検索・更新・削除、セッション管理、health、認証、cleanupを提供します。

The source viewer output is not an independently verified, verbatim transcript of the original media. It can be partial or indeterminate; always inspect completeness, warnings, and verifiedComplete:false before publishing it.

ソースビューアの出力は元音声・動画との独立検証済み逐語録ではありません。部分結果や判定不能になり得るため、公開前に completeness、warnings、verifiedComplete:false を必ず確認してください。

Related MCP server: notebooklm-mcp

Features and tools / 機能・ツール

Questions and sources: ask_question, add_source (URL or pasted text), add_audio_source, add_youtube_source, wait_for_source_ready, export_transcript Audio Overview: generate_audio, get_audio_status, download_audio Notebook library: add_notebook, list_notebooks, get_notebook, select_notebook, update_notebook, remove_notebook, search_notebooks, get_library_stats Sessions/system: list_sessions, close_session, reset_session, get_health, setup_auth; compatibility endpoints re_auth (unavailable/fail-closed) and cleanup_data (preview-only)

Full schemas and return envelopes are in docs/tools.md.

各ツールの引数、戻り値、上限は docs/tools.md にあります。add_audio_source は外部文字起こしサービスを呼ばず、add_youtube_source は公開URLだけを受け付けます。

Install and register / インストールと登録

Give Codex or Claude Code this repository URL and ask it to set up the MCP. The agent-facing, safe one-prompt procedure is docs/agent-setup.md; it uses ./scripts/bootstrap.sh --auto and is the only supported installation path.

Requirements are Git, Node.js 22.13+, npm, and Codex CLI and/or Claude Code. Bootstrap creates the default private audio input at $HOME/notebooklm-audio-inbox (mode 0700) unless a safe --audio-root is explicitly supplied. It validates the reviewed release lineage, installs dependencies without package lifecycle scripts, builds, tests, runs doctor, and makes client registration transactional with read-back verification.

Bootstrap requires a real Git checkout because lineage verification needs Git history. A *-source.tar.gz release archive has no .git; use it for inspection or audit, not one-prompt installation.

Bootstrap manages only the reserved server names notebooklm-audio and notebooklm; it cannot inventory arbitrary aliases. Remove conflicting custom aliases manually before setup. npx notebooklm-mcp@latest is upstream-only and lacks this fork's custom tools; do not install it beside this fork, register dist/index.js directly, or manually merge upstream during setup. Managed-name conflicts fail safely before bootstrap modifies an unidentifiable registration.

Cooperative installs are serialized by fail-closed per-client transaction locks held from inventory through rollback. Existing locks are never auto-broken, even when PID metadata looks stale. Same-user direct CLI/config writers do not honor these locks, so pause them for the full installation; the installer does not claim atomicity against non-cooperating writers.

登録は docs/agent-setup.md の手順だけを使用してください。notebooklm-audio だけを登録し、上流の npx notebooklm-mcp@latest や dist/index.js の直接登録、インストール時の上流マージは行いません。既存MCPとの競合を安全に判別できない場合、bootstrapは設定変更前に停止します。

After a successful install, restart every registered client. Both clients use the same per-OS-user browser profile. インストール成功後は、登録した各クライアントを再起動してください。CodexとClaude Codeは同一OSユーザー内で同じブラウザプロファイルを利用します。

Authentication / 認証

In the same OS user that will run the MCP server, ask either client:

Run notebooklm-audio setup_auth with show_browser=true.

ログイン画面を表示してGoogleログインを完了してください。setup_auth は既存の認証情報を意図的に削除しませんが、対話ログインにより永続プロファイルやセッションが更新されるため、状態保持を保証しません。認証プロファイルはOSユーザーのアプリデータ領域に保存されます。re_auth は現在利用不可で、アカウント切替や認証削除は行いません。VPS/headless Linuxでは初回のみ xvfb-run、noVNC、またはSSH X11で表示を提供し、その後は HEADLESS=true で常駐できます。rootとサービスユーザーでプロファイルを共有しないでください。

Workflows / ワークフロー

1. Select a notebook with select_notebook, or pass notebook_id/notebook_url on each call.

2. Website: add_source(type="url"); YouTube: add_youtube_source(url); local audio: add_audio_source(file_paths=[...]).

3. Wait with wait_for_source_ready(source_names=[...]).

4. Ask with ask_question, or extract UI text with export_transcript.

5. For Audio Overview use generate_audio → get_audio_status → download_audio.

Audio limits: 1–10 files per call, supported extensions (mp3, m4a, aac, wav, flac, ogg, opus), 200 MiB per file / 500 MiB total. Files must be regular files beneath the configured --audio-root. NotebookLM indexing remains asynchronous.

音声は1回1〜10ファイル、対応拡張子は上記のみ、1ファイル200 MiB・合計500 MiBまでです。--audio-root 配下の通常ファイルだけが対象で、登録成功後もNotebookLMの解析は非同期です。必ず wait_for_source_ready を実行してから質問・出力してください。

HTTP loopback and security / HTTPループバックと安全性

export NOTEBOOKLM_HTTP_BEARER_TOKEN="$(openssl rand -hex 32)"
HEADLESS=true ./scripts/start-http.sh

The server binds to 127.0.0.1 (and uses /mcp plus /healthz). Bearer authentication is required; this is a single-principal trust domain. Never commit the token, expose cleartext HTTP publicly, or share one token across tenants. For remote access, put TLS and authentication in a separately managed reverse proxy or private Tailscale network. The stdio transport is the default and avoids opening a network listener.

The launcher environment retains compatibility with the two-key stdio form (NOTEBOOKLM_NODE_BIN and NOTEBOOKLM_AUDIO_ROOTS); its bearer token is optional for stdio and mandatory for HTTP. The installer may write the current three-key form including NOTEBOOKLM_HTTP_BEARER_TOKEN. Do not edit or expose .audio-roots.env.

HTTPは 127.0.0.1 のみにbindし、Bearer token（32 byte以上）を要求します。tokenをコミットせず、平文HTTPを公開せず、複数テナントで共有しないでください。遠隔利用はTLS・認証付きリバースプロキシまたは非公開Tailscaleを前段に置きます。既定のstdioはネットワーク待受を開きません。

Generate a fresh token per deployment with a secret manager or openssl rand -hex 32; do not paste a reusable token into shell history, documentation, or source control. デプロイごとにsecret managerまたは openssl rand -hex 32 で新しいtokenを生成し、再利用可能なtokenを履歴・文書・ソースへ貼り付けないでください。

Limits and unsupported features / 制限と未対応

This fork automates the NotebookLM web UI and may require selector updates when Google changes it. export_transcript is UI extraction, not source/media verification or external speech recognition. Google Drive, generic PDF/DOCX/image uploads, arbitrary local files, multi-tenant shared auth, and non-audio Studio artifacts are unsupported. Do not treat an add_* success receipt as completed indexing.

GoogleがUIを変更するとセレクタ更新が必要です。export_transcript はUI抽出であり、元メディア検証や外部ASRではありません。Drive、一般PDF/DOCX/画像、任意ローカルファイル、共有マルチテナント認証、音声以外のStudio成果物は未対応です。add_* のreceiptだけで解析完了と判断しないでください。

There is no promise of API stability across NotebookLM UI changes; pin a reviewed commit for production-like use and re-run the smoke tests after updates. NotebookLMのUI変更に対するAPI互換性は保証しません。継続運用ではレビュー済みcommitを固定し、更新後にsmoke testを再実行してください。

VPS/headless operations / VPS運用

Use one service OS user and one Chrome profile per Google account/trust boundary. Keep the audio inbox private and writable only by that service. Run HTTP on loopback and front it with a private, authenticated proxy if needed. Authentication uses a cross-process base-profile lease: contending runtime/setup operations return profile_busy; runtime may use a disposable isolated profile only with a bootstrap-eligible snapshot, while single never falls back. re_auth is unavailable and fails closed until safe staged-profile switching exists. get_health is offline: runtime_verified is live evidence from this process, snapshot_usable is unexpired persistent-cookie evidence, and neither guarantees Google will accept saved cookies on the next request.

VPSでは実行専用OSユーザーとGoogleアカウントごとのChromeプロファイルを用意し、音声入力ディレクトリをそのユーザーだけが書けるようにします。認証・音声登録は同一プロファイルで直列化し、setup_auth と通常操作を同時実行しません。re_auth は現在利用できません。

Upstream updates / 上流追従

End users never merge upstream code at installation time. Each published fork release records a reviewed upstream base in RELEASE_PROVENANCE.json; “reviewed latest at release” describes that release-review decision, not a promise to fetch whatever upstream publishes later. Install a reviewed release of this fork only.

Maintainers use scripts/update-upstream.sh from a Git checkout, review the diff, preserve the custom audio workflow, run the full verification suite, obtain review approval, and publish a new fork release. Source-only archives have no .git and cannot perform upstream tracking.

For this release, the reviewed upstream commit is also recorded by the durable fork audit tag upstream/notebooklm/v2.0.0 (full ref: refs/tags/upstream/notebooklm/v2.0.0). That audit tag is already public on origin with the reviewed, immutable SHA; this release push contains only main and the custom v0.0.5 tag. Future reviewed integrations use the same upstream/notebooklm/vX.Y.Z convention. The updater only prepares a review candidate: it never creates or pushes tags, merges code, or publishes releases.

利用者はインストール時に上流をマージしません。各forkリリースはレビュー済み上流基点を RELEASE_PROVENANCE.json に記録します。「release時点でレビュー済み最新」とは、公開時に選定・統合・検証した上流状態を指し、利用時に上流最新版を自動取得・結合する意味ではありません。上流追従はメンテナーがレビューと検証を経て新しいforkリリースとして公開します。

Tests and source-only release / テストと配布

npm ci
npm run check
npm test
./scripts/make-source-release.sh

npm run check はformat/lint/build、npm test は音声、YouTube、readiness、transcript、HTTP concurrency、権限、workflow、source-release等の回帰検証を実行します。

Run these checks before publishing a source archive; no generated dist or credentials belong in the archive. source archiveを公開する前に検証を実行し、生成物 dist や認証情報をアーカイブへ含めないでください。

The release contains source, lockfile, scripts, and documentation only—never cookies, Chrome profiles, .env, node_modules, dist, or audio. RELEASE_PROVENANCE.json is the authoritative record of the upstream base, exact provenance, and custom version; the public repository URL for this fork is the one shown at the top of this README.

配布物はソース、lockfile、scripts、ドキュメントだけで、Cookie・Chromeプロファイル・.env・node_modules・dist・音声は含めません。上流基点、正確なprovenance、カスタム版バージョンは RELEASE_PROVENANCE.json を正とし、公開先はREADME冒頭のこのforkのURLです。

Related repositories / 関連リポジトリ

• This fork: https://github.com/sasuketorii/notebooklm_mcp_with — audio/YouTube custom implementation and release process.

• Upstream server: https://github.com/PleasePrompto/notebooklm-mcp — original NotebookLM MCP server and baseline implementation.

• Upstream skill: https://github.com/PleasePrompto/notebooklm-skill — separate agent skill/integration; it is not this server and its npx examples must not be mistaken for this fork's installer.

License / ライセンス

MIT; see LICENSE. Custom changes are distributed as source under the same license, with provenance in RELEASE_PROVENANCE.json.

Japanese operational detail: SETUP_JA.md. English reference: docs/configuration.md, docs/usage-guide.md, docs/troubleshooting.md.