notebooklm-mcp-go

English | 繁體中文

English

A Golang rewrite of PleasePrompto/notebooklm-mcp — an MCP server that lets AI agents (Claude Code, Cursor, Codex…) query Google NotebookLM notebooks for source-grounded, citation-backed answers powered by Gemini.

What's different from the TypeScript original?

All 16 tools from the original are implemented.

Quick Start

# Build
go build -o notebooklm-mcp-go .

# Register as an MCP server (Claude Code)
claude mcp add notebooklm ./notebooklm-mcp-go

# Or add to your claude_desktop_config.json:
# {
#   "mcpServers": {
#     "notebooklm": {
#       "command": "/path/to/notebooklm-mcp-go"
#     }
#   }
# }

How To Use This MCP

This project is an MCP server. You usually do not call its tools manually. Instead, you:

1. Build the binary
2. Register it in your MCP client
3. Ask your AI agent to use NotebookLM
4. The agent calls these tools for you over MCP

Typical user flow

1. Build and register the server.
2. Ask your agent to authenticate:
   • Set up NotebookLM authentication
   • This calls setup_auth and opens Chrome for Google login.
3. Verify status:
   • Check NotebookLM health
   • This calls get_health.
4. Add a notebook to the local library:
   • Add my NotebookLM notebook
   • The agent should collect the NotebookLM URL, description, topics, and use cases, then call add_notebook.
5. Select a default notebook if needed:
   • Use <notebook name> as my default notebook
   • This calls select_notebook.
6. Start asking questions:
   • Ask my notebook to summarize the API design
   • Ask the same session to compare v1 and v2 behaviour
   • This calls ask_question, optionally reusing session_id.

How MCP clients typically interact with it

• Claude Code / Claude Desktop: Register the binary as an MCP server, then ask for actions in natural language.
• Cursor / Codex / other MCP-aware clients: Add the server command in that client's MCP/server config, then instruct the agent normally.
• Direct execution: Running ./notebooklm-mcp-go starts a stdio JSON-RPC MCP server. This is for MCP clients, not for interactive terminal use.

Example prompts you can give your agent

• Set up NotebookLM authentication
• Show NotebookLM server health
• List my notebooks
• Add this NotebookLM notebook to the library
• Select the notebook named <name>
• Ask the active notebook: what are the main design tradeoffs?
• Continue the previous NotebookLM session and ask for implementation steps
• Reset the current NotebookLM session
• Clean up NotebookLM data but keep my library

Client-specific MCP configuration examples

The exact MCP UI and file format can change by client version. The examples below match the current documented patterns for stdio-based local MCP servers.

Claude Desktop / Claude Code

Claude Code can register the server directly from the CLI:

claude mcp add notebooklm ./notebooklm-mcp-go

If you want to configure Claude Desktop manually, add an entry like this to your MCP config JSON:

{
  "mcpServers": {
    "notebooklm": {
      "command": "C:\\Users\\andyl\\Myprogram\\notebooklm-go\\notebooklm-mcp-go.exe",
      "args": [],
      "env": {
        "DEBUG": "0"
      }
    }
  }
}

Notes:

• Replace the command path with your actual built binary location.
• On macOS/Linux, use the absolute binary path such as /Users/you/path/notebooklm-mcp-go.
• If you build frequently, keep the binary path stable so the client config does not need updating.

Cursor

Cursor reads MCP configuration from project-level .cursor/mcp.json or global ~/.cursor/mcp.json.

Project-local example:

{
  "mcpServers": {
    "notebooklm": {
      "command": "${workspaceFolder}/notebooklm-mcp-go",
      "args": [],
      "env": {
        "DEBUG": "0"
      }
    }
  }
}

Windows example using an absolute path:

{
  "mcpServers": {
    "notebooklm": {
      "command": "C:\\Users\\andyl\\Myprogram\\notebooklm-go\\notebooklm-mcp-go.exe",
      "args": [],
      "env": {
        "DEBUG": "0"
      }
    }
  }
}

Notes:

• If you keep the binary in the repo root, ${workspaceFolder}/notebooklm-mcp-go is convenient on macOS/Linux.
• On Windows, prefer the .exe path.
• After editing mcp.json, restart Cursor or reload MCP servers.

Codex

Codex supports MCP through the CLI and shared config.

CLI registration example:

codex mcp add notebooklm -- C:\Users\andyl\Myprogram\notebooklm-go\notebooklm-mcp-go.exe

If you prefer config file setup, add this to ~/.codex/config.toml:

[mcp_servers.notebooklm]
command = "C:\\Users\\andyl\\Myprogram\\notebooklm-go\\notebooklm-mcp-go.exe"
args = []

[mcp_servers.notebooklm.env]
DEBUG = "0"

macOS/Linux example:

[mcp_servers.notebooklm]
command = "/absolute/path/to/notebooklm-mcp-go"
args = []

[mcp_servers.notebooklm.env]
DEBUG = "0"

Notes:

• codex mcp list can be used to verify the server is registered.
• Codex shares MCP configuration between the CLI and IDE extension.
• Keep the server name short and descriptive, for example notebooklm.

Tools

Core

Session Management

System

Library Management

What each tool is for

Recommended operating sequence

If you are using this MCP for the first time, follow this order:

1. setup_auth
2. get_health
3. add_notebook
4. list_notebooks
5. select_notebook
6. ask_question

For ongoing use:

1. get_health
2. list_notebooks or search_notebooks
3. ask_question
4. list_sessions / reset_session / close_session if you need session management

Configuration

Environment Variables

# NotebookLM
NOTEBOOK_URL=https://notebooklm.google.com/notebook/...

# Browser
HEADLESS=true                    # Run headless (default: true)
BROWSER_TIMEOUT=30000            # Timeout in ms

# Sessions
MAX_SESSIONS=10                  # Max concurrent sessions
SESSION_TIMEOUT=900              # Session idle timeout in seconds

# Auto-login (optional)
AUTO_LOGIN_ENABLED=false
LOGIN_EMAIL=you@gmail.com
LOGIN_PASSWORD=yourpassword

# Stealth (human-like behavior)
STEALTH_ENABLED=true
STEALTH_HUMAN_TYPING=true
TYPING_WPM_MIN=160
TYPING_WPM_MAX=240
MIN_DELAY_MS=100
MAX_DELAY_MS=400

# Tool profile
NOTEBOOKLM_PROFILE=full          # minimal | standard | full
NOTEBOOKLM_DISABLED_TOOLS=cleanup_data,re_auth

CLI Config Commands

# Show current settings
./notebooklm-mcp-go config get

# Set tool profile
./notebooklm-mcp-go config set profile minimal
./notebooklm-mcp-go config set profile standard
./notebooklm-mcp-go config set profile full

# Disable specific tools
./notebooklm-mcp-go config set disabled-tools "cleanup_data,re_auth"

# Reset to defaults
./notebooklm-mcp-go config reset

Settings are saved to ~/.config/notebooklm-mcp/settings.json.

What the CLI config affects

• profile: Limits which tools are exposed to the MCP client.
• disabled-tools: Hides selected tools even if the current profile would normally allow them.
• These settings affect the tool list returned by the server at startup.

Profiles

Data Paths

Library: <data>/library.json
Auth state: <data>/browser_state/state.json
Chrome profile: <data>/chrome_profile/

Architecture

Your Task
  └─► Claude / Codex / Cursor
        └─► MCP Server (JSON-RPC over stdio)
              └─► go-rod (Chrome DevTools Protocol)
                    └─► Chrome / Chromium
                          └─► NotebookLM (Gemini 2.5)
                                └─► Your Docs

Package Structure

.
├── main.go                          # Entry point + CLI config
├── internal/
│   ├── config/config.go             # Configuration (env vars + defaults)
│   ├── auth/auth_manager.go         # Browser state / cookie persistence
│   ├── library/
│   │   ├── types.go                 # Library data types
│   │   └── library.go               # Persistent notebook library (library.json)
│   ├── session/session.go           # Browser sessions + session manager
│   ├── tools/
│   │   ├── definitions.go           # MCP tool definitions (schemas + descriptions)
│   │   └── handlers.go              # Tool implementation logic
│   ├── mcp/server.go                # JSON-RPC 2.0 MCP server (stdio transport)
│   └── utils/
│       ├── logger.go                # Structured logging to stderr
│       └── settings.go              # Profile/tool filtering settings
└── go.mod

First-Time Setup

1. Build the binary: go build -o notebooklm-mcp-go .
2. Register with your MCP client
3. Ask Claude: "Set up NotebookLM authentication" → calls setup_auth
4. A Chrome window opens — log in to your Google account
5. After login, auth state is saved to disk automatically
6. Verify: "Check NotebookLM health" → calls get_health
7. Add a notebook: "Add my NotebookLM notebook" → Claude guides you through add_notebook
8. Start querying: "Ask my notebook about X" → calls ask_question

Common Workflows

1. First-time authentication

1. Start the MCP server through your client.
2. Ask the agent to run setup_auth.
3. Log in to Google in the browser window.
4. Ask the agent to run get_health.
5. Confirm authenticated=true.

2. Add a notebook and query it

1. Create or open a notebook in NotebookLM.
2. Copy its shareable URL.
3. Ask the agent to add it via add_notebook.
4. Optionally call select_notebook.
5. Ask questions through ask_question.

3. Continue a conversation

1. Ask a first question with ask_question.
2. Keep the returned session_id.
3. Ask follow-up questions using the same session_id.
4. Use reset_session if you want a clean conversation without deleting the session record.

4. Troubleshooting

• If NotebookLM stops answering as expected, run get_health.
• If the Google account changed or the login expired, run re_auth.
• If browser/session state is corrupted, run cleanup_data with preview first, then confirm deletion.
• If you want to keep your saved notebooks during cleanup, set preserve_library=true.

Rate Limits

Free Google accounts: 50 queries/day. When the limit is hit:

• ask_question returns a RateLimitError
• Use re_auth to switch to a different Google account
• Or wait until the next day

Upgrade to Google AI Pro/Ultra for 5× higher limits.

License

MIT — same as the original TypeScript project.

繁體中文

中文版請參考 README.zh-TW.md。