get-claudia 1.55.12 → 1.55.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -2,6 +2,20 @@
2
2
 
3
3
  All notable changes to Claudia will be documented in this file.
4
4
 
5
+ ## 1.55.14 (2026-03-16)
6
+
7
+ - **LaunchAgent no longer bakes in --project-dir** -- The standalone background daemon now starts without a `--project-dir` argument. This forces a plist content change for all existing installs, which triggers an automatic LaunchAgent reload on next `claudia setup`, picking up the current Python daemon code. Previously, the plist could be identical across updates, leaving old daemon code running indefinitely even after `pip install --upgrade`.
8
+ - **Cleanup of orphaned empty hash databases** -- On each startup, if the database is already unified and empty hash-named DB files exist (created by stale old-code daemon processes), they are silently removed. Prevents phantom databases from accumulating in `~/.claudia/memory/`.
9
+ - **Root cause:** After the v1.55 consolidation, users whose LaunchAgent was running old pre-unified-DB code would see scheduled jobs (consolidation, backups, decay) operating against an empty `6af67351bcfa.db` while all real memories lived in `claudia.db`. Health check showed `schema_version: 0` and `-1` counts.
10
+
11
+ ## 1.55.13 (2026-03-16)
12
+
13
+ - **Gmail & Calendar MCPs as standard options** -- The standalone `gmail` (`@gongrzhe/server-gmail-autoauth-mcp`) and `google-calendar` (`@gongrzhe/server-calendar-autoauth-mcp`) servers are now first-class options alongside workspace-mcp. Two paths for Google integration: Option A (lightweight, focused, fewer tools) and Option B (all-in-one workspace-mcp with Drive, Docs, Sheets, etc.). Both can coexist.
14
+ - **Auto-detect Gmail/Calendar credentials** -- The installer now checks `~/.gmail-mcp/` and `~/.calendar-mcp/` for existing OAuth credentials. If found, it automatically adds `gmail` and `google-calendar` entries to `.mcp.json`. No manual config needed.
15
+ - **Installer no longer removes standalone MCPs** -- Running `npx get-claudia google` (workspace-mcp setup) no longer deletes existing `gmail` or `google-calendar` entries. Both integration paths coexist safely.
16
+ - **Completion message shows Google MCPs** -- The installer now lists detected Gmail and Calendar servers in the MCP config summary line.
17
+ - **Updated docs** -- CLAUDE.md and .mcp.json.example files document both Google integration paths with setup instructions for each.
18
+
5
19
  ## 1.55.12 (2026-03-15)
6
20
 
7
21
  - **Feedback skill** -- New `/feedback` command lets users share bugs, ideas, or suggestions. Claudia collects system context (version, OS, memory count, daemon health), builds a pre-filled GitHub Discussion URL, and opens it in the browser. The user reviews and submits. No data is sent without their knowledge.
@@ -69,20 +69,27 @@ export function buildApiEnableUrl(projectNumber, tier) {
69
69
  }
70
70
 
71
71
  /**
72
- * Detect old Google MCP server entries in .mcp.json.
73
- * Returns { hasOldGmail, hasOldCalendar, hasWorkspace }.
72
+ * Detect Google MCP server entries in .mcp.json.
73
+ * Returns { hasGmail, hasCalendar, hasWorkspace }.
74
+ *
75
+ * gmail and google-calendar are valid standalone options (lightweight, focused),
76
+ * not legacy entries. They can coexist with google_workspace.
74
77
  */
75
78
  export function detectOldGoogleMcp(targetPath) {
76
79
  const mcpPath = join(targetPath, '.mcp.json');
77
- const result = { hasOldGmail: false, hasOldCalendar: false, hasWorkspace: false };
80
+ const result = { hasGmail: false, hasCalendar: false, hasWorkspace: false,
81
+ // Keep backward-compat aliases for callers that check the old property names
82
+ get hasOldGmail() { return this.hasGmail; },
83
+ get hasOldCalendar() { return this.hasCalendar; },
84
+ };
78
85
 
79
86
  if (!existsSync(mcpPath)) return result;
80
87
 
81
88
  try {
82
89
  const config = JSON.parse(readFileSync(mcpPath, 'utf-8'));
83
90
  const servers = config.mcpServers || {};
84
- result.hasOldGmail = !!servers.gmail;
85
- result.hasOldCalendar = !!servers['google-calendar'];
91
+ result.hasGmail = !!servers.gmail;
92
+ result.hasCalendar = !!servers['google-calendar'];
86
93
  result.hasWorkspace = !!servers.google_workspace;
87
94
  } catch {
88
95
  // Malformed JSON
@@ -93,7 +100,7 @@ export function detectOldGoogleMcp(targetPath) {
93
100
 
94
101
  /**
95
102
  * Add or update the google_workspace entry in .mcp.json.
96
- * Removes old gmail and google-calendar entries if present.
103
+ * Keeps existing gmail and google-calendar entries (they are valid standalone options).
97
104
  * Creates .mcp.json if it doesn't exist.
98
105
  */
99
106
  export function setupGoogleWorkspace(targetPath, clientId, clientSecret, tier) {
@@ -113,9 +120,8 @@ export function setupGoogleWorkspace(targetPath, clientId, clientSecret, tier) {
113
120
 
114
121
  if (!config.mcpServers) config.mcpServers = {};
115
122
 
116
- // Remove old entries
117
- delete config.mcpServers.gmail;
118
- delete config.mcpServers['google-calendar'];
123
+ // Note: gmail and google-calendar entries are kept if present.
124
+ // They are valid standalone options that can coexist with google_workspace.
119
125
 
120
126
  // Add/update google_workspace
121
127
  config.mcpServers.google_workspace = {
package/bin/index.js CHANGED
@@ -962,6 +962,9 @@ async function main() {
962
962
  ensureDaemonMcpConfig(targetPath, venvPython);
963
963
  }
964
964
 
965
+ // Auto-detect and add Gmail/Calendar MCP entries if credentials exist
966
+ const googleMcpResult = ensureGoogleMcpEntries(targetPath);
967
+
965
968
  // Run preflight check to verify daemon can actually start
966
969
  if (daemonOk && existsSync(venvPython)) {
967
970
  renderer.update('daemon', 'active', 'running preflight...');
@@ -1001,7 +1004,7 @@ async function main() {
1001
1004
 
1002
1005
  // Register LaunchAgent for standalone daemon (macOS only)
1003
1006
  if (daemonOk && process.platform === 'darwin') {
1004
- await ensureLaunchAgent(venvPython, targetPath);
1007
+ await ensureLaunchAgent(venvPython);
1005
1008
  }
1006
1009
 
1007
1010
  // MCP Config step: verify .mcp.json is correct and check stdio server count
@@ -1013,9 +1016,15 @@ async function main() {
1013
1016
  renderer.update('mcp', 'active', 'checking .mcp.json...');
1014
1017
  const mcpCheckResult = checkMcpConfig(targetPath);
1015
1018
  if (mcpCheckResult.hasDaemon && mcpCheckResult.stdioCount >= 1) {
1016
- const serverDetail = mcpCheckResult.stdioCount === 1
1017
- ? 'claudia-memory configured'
1018
- : `claudia-memory + ${mcpCheckResult.stdioCount - 1} other server${mcpCheckResult.stdioCount > 2 ? 's' : ''}`;
1019
+ // Build detail string showing what's configured
1020
+ const extras = [];
1021
+ if (mcpCheckResult.stdioServers.includes('gmail')) extras.push('gmail');
1022
+ if (mcpCheckResult.stdioServers.includes('google-calendar')) extras.push('calendar');
1023
+ const otherCount = mcpCheckResult.stdioCount - 1 - extras.length;
1024
+ const parts = ['claudia-memory'];
1025
+ if (extras.length > 0) parts.push(extras.join(', '));
1026
+ if (otherCount > 0) parts.push(`+${otherCount} more`);
1027
+ const serverDetail = parts.join(' + ');
1019
1028
  renderer.update('mcp', 'done', serverDetail);
1020
1029
  if (!supportsInPlace) renderer.appendLine('mcp', 'done', serverDetail);
1021
1030
  } else if (mcpCheckResult.hasDaemon && mcpCheckResult.stdioCount === 0) {
@@ -1474,6 +1483,71 @@ function ensureDaemonMcpConfig(targetPath, venvPythonPath) {
1474
1483
  writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n');
1475
1484
  }
1476
1485
 
1486
+ /**
1487
+ * Ensure gmail and google-calendar MCP entries exist in .mcp.json
1488
+ * if the user has credentials at ~/.gmail-mcp/ and ~/.calendar-mcp/.
1489
+ * Does not overwrite existing entries. Only adds if credentials are found.
1490
+ * Returns { addedGmail, addedCalendar } indicating what was added.
1491
+ */
1492
+ function ensureGoogleMcpEntries(targetPath) {
1493
+ const mcpPath = join(targetPath, '.mcp.json');
1494
+ const result = { addedGmail: false, addedCalendar: false };
1495
+
1496
+ let config;
1497
+ if (existsSync(mcpPath)) {
1498
+ try {
1499
+ config = JSON.parse(readFileSync(mcpPath, 'utf-8'));
1500
+ } catch {
1501
+ return result; // Malformed JSON -- don't touch
1502
+ }
1503
+ } else {
1504
+ return result; // No .mcp.json yet (ensureDaemonMcpConfig creates it first)
1505
+ }
1506
+
1507
+ if (!config.mcpServers) config.mcpServers = {};
1508
+
1509
+ const home = homedir();
1510
+ let changed = false;
1511
+
1512
+ // Gmail: add if credentials exist and entry doesn't
1513
+ const gmailOauthPath = join(home, '.gmail-mcp', 'gcp-oauth.keys.json');
1514
+ const gmailCredsPath = join(home, '.gmail-mcp', 'credentials.json');
1515
+ if (!config.mcpServers.gmail && existsSync(gmailOauthPath) && existsSync(gmailCredsPath)) {
1516
+ config.mcpServers.gmail = {
1517
+ command: 'npx',
1518
+ args: ['-y', '@gongrzhe/server-gmail-autoauth-mcp@latest'],
1519
+ env: {
1520
+ GMAIL_OAUTH_PATH: gmailOauthPath,
1521
+ GMAIL_CREDENTIALS_PATH: gmailCredsPath,
1522
+ },
1523
+ };
1524
+ result.addedGmail = true;
1525
+ changed = true;
1526
+ }
1527
+
1528
+ // Google Calendar: add if credentials exist and entry doesn't
1529
+ const calOauthPath = join(home, '.calendar-mcp', 'gcp-oauth.keys.json');
1530
+ const calCredsPath = join(home, '.calendar-mcp', 'credentials.json');
1531
+ if (!config.mcpServers['google-calendar'] && existsSync(calOauthPath) && existsSync(calCredsPath)) {
1532
+ config.mcpServers['google-calendar'] = {
1533
+ command: 'npx',
1534
+ args: ['-y', '@gongrzhe/server-calendar-autoauth-mcp@latest'],
1535
+ env: {
1536
+ CALENDAR_OAUTH_PATH: calOauthPath,
1537
+ CALENDAR_CREDENTIALS_PATH: calCredsPath,
1538
+ },
1539
+ };
1540
+ result.addedCalendar = true;
1541
+ changed = true;
1542
+ }
1543
+
1544
+ if (changed) {
1545
+ writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n');
1546
+ }
1547
+
1548
+ return result;
1549
+ }
1550
+
1477
1551
  /**
1478
1552
  * Check .mcp.json configuration and return status.
1479
1553
  * Returns { hasDaemon, stdioCount, stdioServers }.
@@ -1501,7 +1575,7 @@ function checkMcpConfig(targetPath) {
1501
1575
  * The standalone daemon runs 24/7 for scheduled jobs (consolidation, decay, vault sync).
1502
1576
  * This is separate from the MCP daemon that Claude Code spawns per-session.
1503
1577
  */
1504
- async function ensureLaunchAgent(venvPythonPath, projectDir) {
1578
+ async function ensureLaunchAgent(venvPythonPath) {
1505
1579
  const plistDir = join(homedir(), 'Library', 'LaunchAgents');
1506
1580
  const plistPath = join(plistDir, 'com.claudia.memory.plist');
1507
1581
 
@@ -1517,8 +1591,6 @@ async function ensureLaunchAgent(venvPythonPath, projectDir) {
1517
1591
  <string>-m</string>
1518
1592
  <string>claudia_memory</string>
1519
1593
  <string>--standalone</string>
1520
- <string>--project-dir</string>
1521
- <string>${projectDir}</string>
1522
1594
  </array>
1523
1595
  <key>WorkingDirectory</key>
1524
1596
  <string>${join(homedir(), '.claudia', 'daemon')}</string>
@@ -1713,9 +1785,9 @@ async function runGoogleSetup() {
1713
1785
  // Detect existing state
1714
1786
  const state = detectOldGoogleMcp(targetPath);
1715
1787
 
1716
- if (state.hasOldGmail || state.hasOldCalendar) {
1717
- console.log(` ${colors.yellow}→${colors.reset} Found old Gmail/Calendar MCP servers. These will be replaced.`);
1718
- console.log(` ${colors.dim}Same GCP credentials work with the new server.${colors.reset}`);
1788
+ if (state.hasGmail || state.hasCalendar) {
1789
+ console.log(` ${colors.yellow}→${colors.reset} Found standalone Gmail/Calendar MCP servers. These will be kept.`);
1790
+ console.log(` ${colors.dim}Both options work side by side. Workspace MCP adds Drive, Docs, Sheets, and more.${colors.reset}`);
1719
1791
  console.log('');
1720
1792
  }
1721
1793
 
@@ -1761,8 +1833,8 @@ async function runGoogleSetup() {
1761
1833
  console.log('');
1762
1834
  console.log(` ${colors.cyan}✓${colors.reset} Google Workspace MCP configured (${colors.bold}${tier}${colors.reset} tier)`);
1763
1835
 
1764
- if (state.hasOldGmail || state.hasOldCalendar) {
1765
- console.log(` ${colors.cyan}✓${colors.reset} Old Gmail/Calendar entries removed`);
1836
+ if (state.hasGmail || state.hasCalendar) {
1837
+ console.log(` ${colors.cyan}✓${colors.reset} Standalone Gmail/Calendar MCP servers kept alongside Workspace`);
1766
1838
  }
1767
1839
 
1768
1840
  // Build one-click API enablement URL
@@ -195,7 +195,16 @@ def _auto_consolidate() -> None:
195
195
  fetch=True,
196
196
  )
197
197
  if rows and rows[0]["value"] == "true":
198
- logger.debug("Database already unified, skipping consolidation")
198
+ # Unified. Clean up any empty hash DBs that stale daemon instances may have
199
+ # created (old standalone daemons running pre-unified-DB code create a fresh
200
+ # empty hash DB on startup if the original was deleted by consolidation).
201
+ all_hash_dbs = scan_hash_databases(memory_dir)
202
+ empty_dbs = [d for d in all_hash_dbs if not d["has_data"]]
203
+ if empty_dbs:
204
+ logger.info(
205
+ f"Removing {len(empty_dbs)} empty hash DB(s) left by stale standalone daemon"
206
+ )
207
+ cleanup_old_databases(memory_dir, empty_dbs)
199
208
  return
200
209
  except Exception:
201
210
  pass # _meta table might not exist yet
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "get-claudia",
3
- "version": "1.55.12",
3
+ "version": "1.55.14",
4
4
  "description": "An AI assistant who learns how you work.",
5
5
  "keywords": [
6
6
  "claudia",
@@ -6,6 +6,24 @@
6
6
  "_description": "Claudia memory system with vector search",
7
7
  "_setup": "Auto-configured by the installer (npx get-claudia). The installer creates a Python venv at ~/.claudia/daemon/venv/ and sets the correct command path in .mcp.json automatically."
8
8
  },
9
+ "gmail": {
10
+ "command": "npx",
11
+ "args": ["-y", "@gongrzhe/server-gmail-autoauth-mcp@latest"],
12
+ "env": {
13
+ "GMAIL_OAUTH_PATH": "",
14
+ "GMAIL_CREDENTIALS_PATH": ""
15
+ },
16
+ "_setup": "Lightweight Gmail-only MCP. Requires Google Cloud OAuth credentials. Run: npx @gongrzhe/server-gmail-autoauth-mcp auth"
17
+ },
18
+ "google-calendar": {
19
+ "command": "npx",
20
+ "args": ["-y", "@gongrzhe/server-calendar-autoauth-mcp@latest"],
21
+ "env": {
22
+ "CALENDAR_OAUTH_PATH": "",
23
+ "CALENDAR_CREDENTIALS_PATH": ""
24
+ },
25
+ "_setup": "Lightweight Calendar-only MCP. Requires Google Cloud OAuth credentials. Run: npx @gongrzhe/server-calendar-autoauth-mcp auth"
26
+ },
9
27
  "google_workspace": {
10
28
  "command": "uvx",
11
29
  "args": ["workspace-mcp", "--tool-tier", "core"],
@@ -13,7 +31,7 @@
13
31
  "GOOGLE_OAUTH_CLIENT_ID": "",
14
32
  "GOOGLE_OAUTH_CLIENT_SECRET": ""
15
33
  },
16
- "_setup": "Google Workspace MCP: Gmail, Calendar, Drive, Docs, Sheets, Tasks, and more in one server. Requires Google Cloud OAuth credentials. See Google Integration Setup in CLAUDE.md. Tool tiers: core (43 tools), extended (83), complete (111). Start with core.",
34
+ "_setup": "All-in-one Google Workspace MCP: Gmail, Calendar, Drive, Docs, Sheets, Tasks, and more. Alternative to the standalone gmail + google-calendar servers above. Requires Google Cloud OAuth credentials. See Google Integration Setup in CLAUDE.md.",
17
35
  "_tiers": {
18
36
  "core": "Gmail, Calendar, Drive, Contacts (43 tools, recommended default)",
19
37
  "extended": "Adds Docs, Sheets, Tasks, Chat (83 tools)",
@@ -33,7 +51,8 @@
33
51
 
34
52
  "_notes": {
35
53
  "memory": "Claudia's memory is powered by the claudia-memory daemon (Python MCP server). It provides ~33 tools for semantic search, pattern detection, and relationship tracking. The installer (npx get-claudia) automatically sets up the daemon in a Python venv at ~/.claudia/daemon/venv/ and configures .mcp.json.",
36
- "google_workspace": "Google Workspace uses the workspace-mcp server (taylorwilsdon/google_workspace_mcp). One server covers Gmail, Calendar, Drive, Docs, Sheets, Tasks, and more. Tool tiers control context usage. See Google Integration Setup in CLAUDE.md.",
54
+ "google_options": "Two paths for Google integration: (A) gmail + google-calendar (lightweight, focused, fewer tools) or (B) google_workspace via workspace-mcp (all-in-one, more tools). Both can coexist. See Google Integration Setup in CLAUDE.md.",
55
+ "google_workspace": "Google Workspace uses the workspace-mcp server (taylorwilsdon/google_workspace_mcp). One server covers Gmail, Calendar, Drive, Docs, Sheets, Tasks, and more. Tool tiers control context usage.",
37
56
  "rube": "Rube (by Composio) connects 500+ apps through one HTTP MCP connection. Each user creates their own free Rube account at rube.app. See the Rube section in CLAUDE.md for setup and troubleshooting.",
38
57
  "security": "Each user authenticates with their own accounts and credentials. OAuth tokens are stored locally on your machine, never shared.",
39
58
  "not_included": {
@@ -319,9 +319,20 @@ I adapt to whatever tools are available. When you ask me to do something that ne
319
319
 
320
320
  **Obsidian vault:** My memory syncs to an Obsidian vault at `~/.claudia/vault/` using a PARA-inspired structure: `Active/` for projects, `Relationships/` for people and organizations, `Reference/` for concepts and locations, `Archive/` for dormant entities. Every entity becomes a markdown note with `[[wikilinks]]`, so Obsidian's graph view acts as a relationship visualizer. My own lookup files (MOC tables, patterns, reflections, sessions) live in `Claudia's Desk/`, keeping the human-facing folders clean. The vault syncs on-demand via `claudia vault sync`. SQLite remains the source of truth; the vault is a read projection.
321
321
 
322
- **Google Workspace (MCP):** Google Workspace is provided by the workspace-mcp server ([taylorwilsdon/google_workspace_mcp](https://github.com/taylorwilsdon/google_workspace_mcp)). One server covers Gmail, Calendar, Drive, Docs, Sheets, Tasks, Contacts, and more. Tool tiers control how many tools are exposed: `--tool-tier core` (43 tools, default), `--tool-tier extended` (83 tools), or `--tool-tier complete` (111 tools). When connected, I have access to Gmail, Calendar, Drive, Docs, Sheets, Tasks, and more. I use these tools naturally when you ask me to check email, send messages, look at your calendar, search Drive, or work with documents.
322
+ **Google Integration:** Two paths are available for connecting Google services:
323
323
 
324
- If the MCP tools aren't responding or you see authentication errors, the user needs to set up their Google Cloud credentials. See the **Google Integration Setup** section below.
324
+ **Option A: Gmail + Calendar MCPs** (lightweight, focused)
325
+ - Two separate servers: `gmail` (`@gongrzhe/server-gmail-autoauth-mcp`) and `google-calendar` (`@gongrzhe/server-calendar-autoauth-mcp`)
326
+ - Fewer tools, lower context usage
327
+ - Auth: `npx @gongrzhe/server-gmail-autoauth-mcp auth` and `npx @gongrzhe/server-calendar-autoauth-mcp auth`
328
+ - Credentials stored at `~/.gmail-mcp/` and `~/.calendar-mcp/`
329
+
330
+ **Option B: Google Workspace MCP** (all-in-one)
331
+ - One server (`google_workspace` via [workspace-mcp](https://github.com/taylorwilsdon/google_workspace_mcp)) covers Gmail, Calendar, Drive, Docs, Sheets, Tasks, Contacts, and more
332
+ - Tool tiers: `--tool-tier core` (43 tools, default), `--tool-tier extended` (83 tools), `--tool-tier complete` (111 tools)
333
+ - Auth: `npx get-claudia google` for guided setup
334
+
335
+ Both options can coexist in `.mcp.json`. When both are present, I use whichever tools are available. If the MCP tools aren't responding or you see authentication errors, the user needs to set up their Google Cloud credentials. See the **Google Integration Setup** section below.
325
336
 
326
337
  **Rube (500+ Apps):** Rube (by Composio) is an optional MCP aggregator that connects Claudia to hundreds of apps through a single server. Each user creates their own free Rube account, connects the apps they want via one-click OAuth, and Claudia gets access to all of them through one MCP connection.
327
338
 
@@ -346,7 +357,7 @@ If a user asks about connecting apps, integrations, or any of the services liste
346
357
  | **Calendar** | Google Calendar, Outlook Calendar, Calendly |
347
358
  | **And 500+ more** | Browse the full list at [rube.app](https://rube.app) |
348
359
 
349
- **External integrations** (Google Workspace, Rube, Brave Search) are optional add-ons that extend what I can see and do. I work fully without them. The core value is relationships and context.
360
+ **External integrations** (Gmail, Calendar, Google Workspace, Rube, Brave Search) are optional add-ons that extend what I can see and do. I work fully without them. The core value is relationships and context.
350
361
 
351
362
  ### Rube Setup (Guide Users Through This)
352
363
 
@@ -401,13 +412,40 @@ The MCP tools from Rube will have names like `SLACK_SEND_MESSAGE`, `NOTION_CREAT
401
412
  | Rate limited | Rube has usage limits on the free tier. The user may need to upgrade at rube.app/pricing. |
402
413
  | Want to disconnect an app | Go to Rube dashboard and disconnect the app there. No Claudia config changes needed. |
403
414
 
404
- **Rube vs. workspace-mcp:** Rube works alongside (not instead of) the workspace-mcp server. Workspace-mcp gives a direct connection with no intermediary but requires Google Cloud setup. Rube gives one setup for everything but routes data through Composio servers. Both can coexist. If a user has both workspace-mcp and Rube's Google apps connected, prefer the direct workspace-mcp tools.
415
+ **Rube vs. direct Google MCPs:** Rube works alongside (not instead of) the direct Google MCP servers (gmail, google-calendar, or workspace-mcp). Direct servers give a connection with no intermediary but require Google Cloud setup. Rube gives one setup for everything but routes data through Composio servers. All can coexist. If a user has both direct Google MCPs and Rube's Google apps connected, prefer the direct MCP tools.
405
416
 
406
417
  ### Google Integration Setup
407
418
 
408
- **Recommended:** Run `npx get-claudia google` for a guided setup that generates a one-click API enablement URL.
419
+ Both Google integration paths require a Google Cloud project with OAuth credentials. The same GCP project works for either option.
409
420
 
410
- The workspace-mcp server requires your own Google Cloud credentials. Each user sets this up once:
421
+ **Option A: Gmail + Calendar MCPs (lightweight)**
422
+
423
+ 1. Go to [Google Cloud Console](https://console.cloud.google.com/)
424
+ 2. Create a new project (or select an existing one)
425
+ 3. Enable the **Gmail API** and **Google Calendar API** in APIs & Services > Library
426
+ 4. Create OAuth credentials (APIs & Services > Credentials > OAuth client ID, Desktop app type)
427
+ 5. Download the OAuth JSON file as `gcp-oauth.keys.json`
428
+ 6. Authenticate each service:
429
+ ```
430
+ npx @gongrzhe/server-gmail-autoauth-mcp auth
431
+ npx @gongrzhe/server-calendar-autoauth-mcp auth
432
+ ```
433
+ Each opens your browser for Google sign-in. Tokens stored at `~/.gmail-mcp/` and `~/.calendar-mcp/`.
434
+ 7. Set the paths in `.mcp.json`:
435
+ ```json
436
+ "gmail": {
437
+ "env": {
438
+ "GMAIL_OAUTH_PATH": "~/.gmail-mcp/gcp-oauth.keys.json",
439
+ "GMAIL_CREDENTIALS_PATH": "~/.gmail-mcp/credentials.json"
440
+ }
441
+ }
442
+ ```
443
+ (Same pattern for `google-calendar` with `~/.calendar-mcp/` paths.)
444
+ 8. Restart Claude Code.
445
+
446
+ **Option B: Google Workspace MCP (all-in-one)**
447
+
448
+ **Recommended:** Run `npx get-claudia google` for a guided setup that generates a one-click API enablement URL.
411
449
 
412
450
  1. Go to [Google Cloud Console](https://console.cloud.google.com/)
413
451
  2. Create a new project (or select an existing one)
@@ -443,7 +481,7 @@ The workspace-mcp server requires your own Google Cloud credentials. Each user s
443
481
  7. Restart Claude Code. On first run, the server opens your browser for Google sign-in. Tokens are stored locally for future sessions.
444
482
  8. **Re-authentication after enabling new APIs:** If you enable additional APIs after your initial sign-in, you must re-authenticate. Delete `~/.workspace-mcp/token.json` and restart Claude Code to trigger a new sign-in with the updated scopes.
445
483
 
446
- **Migrating from the old setup:** If you previously used separate Gmail and Calendar MCP servers, the same GCP project works. Just enable any additional APIs in your existing project, copy over the Client ID and Client Secret into `GOOGLE_OAUTH_CLIENT_ID` and `GOOGLE_OAUTH_CLIENT_SECRET`, and update `.mcp.json` to use the `google_workspace` server entry instead of the old individual entries.
484
+ **Using both:** Option A and Option B can coexist. If you already have the standalone Gmail/Calendar MCPs and want to add Drive, Docs, etc., just add the `google_workspace` entry alongside them.
447
485
 
448
486
  ---
449
487