# Multi-Account Management
The NotebookLM MCP server supports multiple Google accounts with automatic rotation when rate limits are hit.
## Overview
NotebookLM has a **50 queries per day limit** per Google account (free tier). With multi-account support, the server can automatically switch to another account when the limit is reached, giving you up to **150 queries/day** with 3 accounts.
## Architecture
```
┌─────────────────────────────────────────────────────────────┐
│ Account Manager │
├─────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Account 1 │ │ Account 2 │ │ Account 3 │ │
│ │ (Primary) │ │ (Secondary) │ │ (Tertiary) │ │
│ │ 50/day │ │ 50/day │ │ 50/day │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
│ Rotation Strategy: least_used | round_robin | failover │
└─────────────────────────────────────────────────────────────┘
```
## Configuration
### Account Directory Structure
Each account has its own directory under `DATA_DIR/accounts/`:
```
DATA_DIR/
├── accounts/
│ ├── account-{timestamp1}/
│ │ ├── config.json # Account configuration
│ │ ├── quota.json # Usage tracking
│ │ ├── state.json # Account state
│ │ ├── browser_state/
│ │ │ └── state.json # Playwright storage state
│ │ └── profile/ # Chrome profile directory
│ │
│ ├── account-{timestamp2}/
│ │ └── ...
│ │
│ └── config.json # Global accounts config
│
├── browser_state/
│ └── state.json # Active account's state
│
└── chrome_profile/ # Active account's Chrome profile
```
### Account Config File
`accounts/account-{id}/config.json`:
```json
{
"id": "account-1766565732376",
"email": "user@gmail.com",
"enabled": true,
"priority": 1,
"totp_secret": "BASE32SECRET..." // Optional for 2FA
}
```
### Quota Tracking
`accounts/account-{id}/quota.json`:
```json
{
"used": 15,
"limit": 50,
"resetAt": "2025-12-31T00:00:00.000Z",
"lastUpdated": "2025-12-30T10:00:00.000Z"
}
```
### Global Config
`accounts/config.json`:
```json
{
"rotationStrategy": "least_used",
"autoRotateOnRateLimit": true,
"maxConsecutiveFailures": 3
}
```
## Rotation Strategies
### `least_used` (Default)
Selects the account with the most remaining quota. Best for maximizing throughput.
### `round_robin`
Cycles through accounts in order. Best for even distribution.
### `failover`
Uses accounts in priority order. Only switches when current account fails.
## Rate Limit Detection
The server detects rate limits via:
1. **Response text**: "Le système n'a pas pu répondre" (general error)
2. **Input field**: "Vous avez atteint la limite quotidienne de discussions"
3. **Page body**: Rate limit keywords in French/English
### Detection Keywords
French:
- "limite quotidienne de discussions"
- "atteint la limite quotidienne"
- "vous avez atteint la limite"
- "revenez plus tard"
English:
- "daily limit reached"
- "rate limit exceeded"
- "quota exhausted"
- "too many requests"
## Automatic Rotation Flow
When a rate limit is detected:
```
1. Rate limit detected
↓
2. Mark current account as quota exhausted
↓
3. Close browser sessions (releases profile lock)
↓
4. Wait 2 seconds for Chrome to release files
↓
5. Select next available account (based on strategy)
↓
6. Sync new account's profile to main profile:
- Copy state.json → browser_state/
- Copy profile/ → chrome_profile/
↓
7. Retry the request with new account
```
## Adding a New Account
### Via CLI
```bash
npm run accounts add
```
Follow the interactive prompts to:
1. Enter email address
2. Enter password
3. Optionally enter TOTP secret for 2FA
### Manually
1. Create account directory:
```bash
mkdir -p DATA_DIR/accounts/account-$(date +%s)
```
2. Create `config.json`:
```json
{
"id": "account-...",
"email": "newaccount@gmail.com",
"enabled": true,
"priority": 2
}
```
3. Run auto-login to authenticate:
```bash
npm run accounts test account-... -- --show
```
4. Sync to main profile if this should be the active account.
## CLI Commands
```bash
# List all accounts
npm run accounts list
# Add new account
npm run accounts add
# Test account authentication
npm run accounts test <account-id> -- --show
# Remove account
npm run accounts remove <account-id>
```
## Troubleshooting
### All Accounts Exhausted
If all accounts hit their daily limit:
1. **Wait** until midnight UTC for quotas to reset
2. **Manually reset** quotas for testing:
```bash
echo '{"used": 0, "limit": 50, ...}' > accounts/account-xxx/quota.json
```
### Account Won't Switch
Check if:
1. Profile lock is released (close all Chrome instances)
2. Account has quota remaining
3. Account is enabled in config.json
4. Account hasn't exceeded failure threshold
### Authentication Expired
Re-authenticate the account:
```bash
npm run accounts test <account-id> -- --show
```
Then sync to main profile if needed.
## API Integration
The `/ask` endpoint automatically handles account rotation. No changes needed to API calls.
If rotation fails, the response includes:
```json
{
"success": false,
"error": "NotebookLM rate limit reached... Automatic account rotation failed..."
}
```
## Language Switching
Each account may have a different Google Account language setting. The server uses UI selectors that must match the NotebookLM language.
### Automated Language Switch
Use the provided script to switch an account's language:
```bash
./scripts/switch-account-language.sh --account=mathieu --lang=fr --show
```
**What it does:**
1. Stops the server and Chrome
2. Deletes the Chrome profile cache for the account
3. Re-authenticates (opens browser for login)
4. Syncs the new profile to main
5. Restarts server with the correct `NOTEBOOKLM_UI_LOCALE`
**Important:** The Google Account's language setting must match. Change it at:
https://myaccount.google.com/language
### Environment Variable
Set the UI locale when starting the server:
```bash
NOTEBOOKLM_UI_LOCALE=en node dist/http-wrapper.js
```
See [Adding a Language](../../docs/ADDING_A_LANGUAGE.md) for details on the i18n system.
---
## Best Practices
1. **Use 3+ accounts** for production workloads
2. **Enable TOTP** for unattended authentication
3. **Monitor quotas** via logs or quota.json files
4. **Stagger usage** across accounts to avoid hitting limits simultaneously
5. **Test rotation** before deploying to production
6. **Match UI locale** with each account's Google language setting
