mcp-google-multi 4.3.0-alpha.1 → 4.3.0-alpha.3

package/README.md

@@ -2,6 +2,8 @@
 
 A local [MCP](https://modelcontextprotocol.io) server that gives Claude Code (and any MCP client) access to **Gmail**, **Google Drive**, **Google Calendar**, **Google Sheets**, **Google Docs**, **Google Contacts**, **Google Search Console**, **Google Tasks**, **Google Meet**, and optionally **Google Forms**, **Google Chat**, and **Google Workspace Admin** APIs across multiple Google accounts simultaneously.
 
+[![npm](https://img.shields.io/npm/v/mcp-google-multi?label=npm&color=cb3837)](https://www.npmjs.com/package/mcp-google-multi)
+
 ## Features
 
 - **Multi-account** — manage any number of Google accounts from a single server
@@ -20,9 +22,9 @@ A local [MCP](https://modelcontextprotocol.io) server that gives Claude Code (an
 | `gmail_search` | Search messages with Gmail query syntax |
 | `gmail_read` | Read a full message by ID |
 | `gmail_read_thread` | Read all messages in a thread |
-| `gmail_send` | Send an email |
+| `gmail_send` | Send an email (optional `htmlBody` for multipart/alternative) |
 | `gmail_download_attachment` | Download an email attachment to local disk |
-| `gmail_create_draft` | Create a draft |
+| `gmail_create_draft` | Create a draft (optional `htmlBody` for multipart/alternative) |
 | `gmail_modify_labels` | Add/remove labels on a message (star, archive, mark read, etc.) |
 | `gmail_trash` | Move a message to Trash (recoverable) |
 | `gmail_delete` | Permanently delete a message (irreversible) |
@@ -249,14 +251,25 @@ Enable with `GOOGLE_OPTIONAL_SCOPES=alertcenter` in `.env`.
 
 ### 2. Install & Configure
 
+**Option A — from npm (no clone):**
+
+```bash
+npm install -g mcp-google-multi    # installs the `mcp-google-multi` CLI
+# …or run on demand without installing: npx mcp-google-multi
+```
+
+Published with channel dist-tags — `@latest` (stable), `@dev` (alpha), `@staging` (beta); e.g. `npm i -g mcp-google-multi@dev` for the latest alpha.
+
+**Option B — from source:**
+
 ```bash
 git clone https://github.com/bakissation/mcp-google-multi.git
 cd mcp-google-multi
-npm install
+npm install && npm run build
 cp .env.example .env
 ```
 
-Edit `.env`:
+Create a `.env` (from source, `.env.example` is the template; from npm, make one in the directory you'll run the server from) with:
 
 ```env
 GOOGLE_CLIENT_ID=your_client_id_here
@@ -310,6 +323,24 @@ Or add it manually to your Claude Code MCP config:
 }
 ```
 
+If you installed from npm, point at the package instead and pass config via `env` (authenticate first with `mcp-google-multi auth --account <alias>`):
+
+```json
+{
+  "mcpServers": {
+    "google-multi": {
+      "command": "npx",
+      "args": ["-y", "mcp-google-multi"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your_client_id_here",
+        "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
+        "GOOGLE_ACCOUNTS": "work:you@company.com,personal:you@gmail.com"
+      }
+    }
+  }
+}
+```
+
 ## Migrating from v3
 
 v4.0.0 grows the base OAuth scope set (Tasks and Meet are now included by default). Existing v3 tokens lack those scopes and the corresponding tools will 403.

package/dist/accounts.d.ts

@@ -1,6 +1,7 @@
 export interface AccountConfig {
     email: string;
     tokenPath: string;
+    encPath: string;
 }
 /** Tuple of account aliases (at least one) — usable with z.enum() */
 export declare const ACCOUNTS: [string, ...string[]];

package/dist/accounts.js

@@ -3,7 +3,9 @@ import { fileURLToPath } from 'node:url';
 import path from 'node:path';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 dotenv.config({ path: path.resolve(__dirname, '..', '.env') });
-const tokenDir = path.resolve(__dirname, '..', 'tokens');
+const tokenDir = process.env.TOKEN_STORE_PATH
+    ? path.resolve(process.env.TOKEN_STORE_PATH)
+    : path.resolve(__dirname, '..', 'tokens');
 /**
  * Parse accounts from the GOOGLE_ACCOUNTS env var.
  * Format: "alias1:email1,alias2:email2,..."
@@ -39,6 +41,7 @@ function parseAccounts() {
         configs[alias] = {
             email,
             tokenPath: path.join(tokenDir, alias, 'token.json'),
+            encPath: path.join(tokenDir, `${alias}.enc`),
         };
     }
     if (aliases.length === 0) {

package/dist/auth.js

@@ -2,11 +2,10 @@ import { google } from 'googleapis';
 import http from 'node:http';
 import { URL } from 'node:url';
 import { randomBytes } from 'node:crypto';
-import fs from 'node:fs/promises';
-import path from 'node:path';
 import open from 'open';
 import destroyer from 'server-destroy';
 import { ACCOUNTS, ACCOUNT_CONFIG } from './accounts.js';
+import { writeToken } from './token-store.js';
 // ─── Scope tiers ────────────────────────────────────────────────────────
 //
 // BASE: always granted. Existing v3 surface + Tasks + Meet (added in v4.0.0).
@@ -98,6 +97,10 @@ export async function runAuthFlow(args) {
     }
     const config = ACCOUNT_CONFIG[alias];
     const scopes = resolveScopesForAccount(alias);
+    if (!process.env.MASTER_KEY) {
+        console.error('MASTER_KEY is not set. Generate one (openssl rand -base64 32) and add it to .env before authenticating.');
+        process.exit(1);
+    }
     const oauth2Client = new google.auth.OAuth2(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
     // CSRF protection for the OAuth callback (RFC 6749 §10.12).
     const expectedState = randomBytes(32).toString('hex');
@@ -145,13 +148,11 @@ export async function runAuthFlow(args) {
                         return;
                     }
                     const { tokens } = await oauth2Client.getToken(code);
-                    await fs.mkdir(path.dirname(config.tokenPath), { recursive: true });
-                    // 0o600: tokens grant full account access; keep them user-only.
-                    await fs.writeFile(config.tokenPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
+                    writeToken(alias, tokens);
                     res.writeHead(200, { 'Content-Type': 'text/html' });
                     res.end('<h2>Authentication successful!</h2><p>You can close this tab.</p>');
                     server.destroy();
-                    console.log(`Token saved to ${config.tokenPath}`);
+                    console.log(`Token saved (encrypted) for ${alias}.`);
                     resolve();
                 }
             }

package/dist/client.js

@@ -1,6 +1,6 @@
 import { google } from 'googleapis';
-import fs from 'node:fs/promises';
 import { ACCOUNT_CONFIG } from './accounts.js';
+import { readToken, writeToken } from './token-store.js';
 export async function getClient(account) {
     const config = ACCOUNT_CONFIG[account];
     if (!process.env.GOOGLE_CLIENT_ID || !process.env.GOOGLE_CLIENT_SECRET) {
@@ -8,26 +8,15 @@ export async function getClient(account) {
             'Check that .env exists in the project root or pass them as env vars.');
     }
     const oauth2Client = new google.auth.OAuth2(process.env.GOOGLE_CLIENT_ID, process.env.GOOGLE_CLIENT_SECRET, 'http://localhost:4242/oauth2callback');
-    let tokenData;
-    try {
-        const raw = await fs.readFile(config.tokenPath, 'utf-8');
-        tokenData = JSON.parse(raw);
-    }
-    catch {
-        throw new Error(`No token file found for account "${account}" at ${config.tokenPath}. ` +
-            `Run: node dist/index.js auth --account ${account}`);
+    const tokenData = readToken(account);
+    if (!tokenData) {
+        throw new Error(`No token found for account "${account}" (${config.email}). ` +
+            `Run: npx mcp-google-multi auth --account ${account}`);
     }
     oauth2Client.setCredentials(tokenData);
-    // 0o600: tokens grant full account access; keep them user-only.
-    oauth2Client.on('tokens', async (tokens) => {
-        try {
-            const existing = JSON.parse(await fs.readFile(config.tokenPath, 'utf-8'));
-            const merged = { ...existing, ...tokens };
-            await fs.writeFile(config.tokenPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
-        }
-        catch {
-            await fs.writeFile(config.tokenPath, JSON.stringify(tokens, null, 2), { mode: 0o600 });
-        }
+    oauth2Client.on('tokens', (tokens) => {
+        const existing = readToken(account) ?? {};
+        writeToken(account, { ...existing, ...tokens });
     });
     return oauth2Client;
 }

package/dist/index.js

@@ -26,6 +26,11 @@ async function main() {
         await runAuthFlow(process.argv);
         return;
     }
+    if (process.argv.includes('migrate-tokens')) {
+        const { runMigrateTokens } = await import('./migrate-tokens.js');
+        runMigrateTokens();
+        return;
+    }
     // MCP server mode — no console.log (stdio is the MCP channel)
     const server = new McpServer({
         name: 'mcp-google-multi',

package/dist/migrate-tokens.d.ts

@@ -0,0 +1 @@
+export declare function runMigrateTokens(): void;

package/dist/migrate-tokens.js

@@ -0,0 +1,22 @@
+import fs from 'node:fs';
+import { ACCOUNTS, ACCOUNT_CONFIG } from './accounts.js';
+import { writeToken, hasToken } from './token-store.js';
+export function runMigrateTokens() {
+    let migrated = 0;
+    let skipped = 0;
+    for (const alias of ACCOUNTS) {
+        const plain = ACCOUNT_CONFIG[alias].tokenPath;
+        if (!fs.existsSync(plain))
+            continue;
+        if (hasToken(alias)) {
+            console.log(`• ${alias}: encrypted token already exists, skipping`);
+            skipped++;
+            continue;
+        }
+        writeToken(alias, JSON.parse(fs.readFileSync(plain, 'utf8')));
+        console.log(`✓ ${alias}: migrated ${plain} → encrypted store`);
+        migrated++;
+    }
+    console.log(`Done. ${migrated} migrated, ${skipped} skipped. ` +
+        'Delete the plaintext tokens/<alias>/token.json once verified.');
+}

package/dist/token-store.d.ts

@@ -0,0 +1,7 @@
+import type { TokenData } from './types.js';
+export declare function deriveKey(masterKey: string): Buffer;
+export declare function encryptToken(data: object, masterKey: string): string;
+export declare function decryptToken(fileContents: string, masterKey: string): TokenData;
+export declare function readToken(alias: string): TokenData | null;
+export declare function writeToken(alias: string, data: object): void;
+export declare function hasToken(alias: string): boolean;

package/dist/token-store.js

@@ -0,0 +1,66 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { ACCOUNT_CONFIG } from './accounts.js';
+const ENC_VERSION = 1;
+const ALGO = 'aes-256-gcm';
+export function deriveKey(masterKey) {
+    if (!masterKey) {
+        throw new Error('MASTER_KEY is required to encrypt/decrypt tokens. Generate one with: openssl rand -base64 32');
+    }
+    const raw = Buffer.from(masterKey, 'base64');
+    if (raw.length === 32)
+        return raw;
+    return createHash('sha256').update(masterKey, 'utf8').digest();
+}
+export function encryptToken(data, masterKey) {
+    const key = deriveKey(masterKey);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv(ALGO, key, iv);
+    const ciphertext = Buffer.concat([
+        cipher.update(Buffer.from(JSON.stringify(data), 'utf8')),
+        cipher.final(),
+    ]);
+    const file = {
+        v: ENC_VERSION,
+        iv: iv.toString('base64'),
+        tag: cipher.getAuthTag().toString('base64'),
+        data: ciphertext.toString('base64'),
+    };
+    return JSON.stringify(file);
+}
+export function decryptToken(fileContents, masterKey) {
+    const key = deriveKey(masterKey);
+    const file = JSON.parse(fileContents);
+    if (file.v !== ENC_VERSION) {
+        throw new Error(`Unsupported token file version: ${file.v}`);
+    }
+    const decipher = createDecipheriv(ALGO, key, Buffer.from(file.iv, 'base64'));
+    decipher.setAuthTag(Buffer.from(file.tag, 'base64'));
+    const plaintext = Buffer.concat([
+        decipher.update(Buffer.from(file.data, 'base64')),
+        decipher.final(),
+    ]);
+    return JSON.parse(plaintext.toString('utf8'));
+}
+function masterKey() {
+    return process.env.MASTER_KEY ?? '';
+}
+export function readToken(alias) {
+    let contents;
+    try {
+        contents = fs.readFileSync(ACCOUNT_CONFIG[alias].encPath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+    return decryptToken(contents, masterKey());
+}
+export function writeToken(alias, data) {
+    const p = ACCOUNT_CONFIG[alias].encPath;
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    fs.writeFileSync(p, encryptToken(data, masterKey()), { mode: 0o600 });
+}
+export function hasToken(alias) {
+    return fs.existsSync(ACCOUNT_CONFIG[alias].encPath);
+}

package/dist/tools/gmail-mime.d.ts

@@ -14,3 +14,12 @@ export declare function encodeAddressHeader(value: string): string;
  * Normalize bare `\n` or `\r` to CRLF.
  */
 export declare function normalizeBodyLineEndings(body: string): string;
+/**
+ * Build a multipart/alternative body so HTML-capable clients render the rich
+ * version and plain clients fall back. Returns the header value AND the body.
+ * Caller composes the full message: headers (including this Content-Type) + CRLF + body.
+ */
+export declare function buildMultipartAlternative(plainBody: string, htmlBody: string): {
+    contentType: string;
+    body: string;
+};

package/dist/tools/gmail-mime.js

@@ -1,3 +1,4 @@
+import { randomBytes } from 'node:crypto';
 /**
  * RFC 2047 encoded-word (`=?utf-8?B?...?=`) for non-ASCII header text.
  * Long values are split into multiple <=75-char encoded-words separated
@@ -62,3 +63,37 @@ export function encodeAddressHeader(value) {
 export function normalizeBodyLineEndings(body) {
     return body.replace(/\r\n|\r|\n/g, '\r\n');
 }
+/**
+ * RFC 2046 §5.1.1 boundary token: 1-70 chars from a restricted set, no trailing space.
+ * randomBytes hex output is only [0-9a-f], all of which are bcharsnospace.
+ */
+function generateMimeBoundary() {
+    // 5-char prefix + 32 hex chars = 37 chars, well under the 70-char limit.
+    return `=_gm_${randomBytes(16).toString('hex')}`;
+}
+/**
+ * Build a multipart/alternative body so HTML-capable clients render the rich
+ * version and plain clients fall back. Returns the header value AND the body.
+ * Caller composes the full message: headers (including this Content-Type) + CRLF + body.
+ */
+export function buildMultipartAlternative(plainBody, htmlBody) {
+    const boundary = generateMimeBoundary();
+    const parts = [
+        `--${boundary}`,
+        'Content-Type: text/plain; charset="UTF-8"',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        normalizeBodyLineEndings(plainBody),
+        `--${boundary}`,
+        'Content-Type: text/html; charset="UTF-8"',
+        'Content-Transfer-Encoding: 8bit',
+        '',
+        normalizeBodyLineEndings(htmlBody),
+        `--${boundary}--`,
+        '',
+    ];
+    return {
+        contentType: `multipart/alternative; boundary="${boundary}"`,
+        body: parts.join('\r\n'),
+    };
+}

package/dist/tools/gmail.js

@@ -3,7 +3,7 @@ import { google } from 'googleapis';
 import { ACCOUNTS } from '../accounts.js';
 import { getClient } from '../client.js';
 import { handleGoogleApiError } from './_errors.js';
-import { encodeAddressHeader, encodeHeaderValue, normalizeBodyLineEndings } from './gmail-mime.js';
+import { buildMultipartAlternative, encodeAddressHeader, encodeHeaderValue, normalizeBodyLineEndings } from './gmail-mime.js';
 import * as path from 'path';
 import * as fs from 'fs';
 const accountEnum = z.enum(ACCOUNTS);
@@ -163,14 +163,16 @@ export function registerGmailTools(server) {
             account: accountEnum.describe('Google account alias'),
             to: z.string().describe('Recipient(s), comma-separated'),
             subject: z.string().describe('Email subject'),
-            body: z.string().describe('Plain text body'),
+            body: z.string().describe('Plain text body (always required; also used as fallback when htmlBody is set)'),
+            htmlBody: z.string().optional()
+                .describe('Optional HTML body. When set, sends multipart/alternative so HTML-capable clients render the rich version. Use bare tags only: <p>, <a>, <br>, <strong>, <em>, <ul><li>.'),
             cc: z.string().optional().describe('CC recipients, comma-separated'),
             replyToMessageId: z.string().optional()
                 .describe('Message ID to reply to (sets In-Reply-To and References headers)'),
             replyToThreadId: z.string().optional()
                 .describe('Thread ID to send the message in'),
         },
-    }, async ({ account, to, subject, body, cc, replyToMessageId, replyToThreadId }) => {
+    }, async ({ account, to, subject, body, htmlBody, cc, replyToMessageId, replyToThreadId }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -180,16 +182,25 @@ export function registerGmailTools(server) {
                 `To: ${encodeAddressHeader(to)}`,
                 `Subject: ${encodeHeaderValue(subject)}`,
                 'MIME-Version: 1.0',
-                'Content-Type: text/plain; charset="UTF-8"',
-                'Content-Transfer-Encoding: 8bit',
             ];
+            let bodyText;
+            if (htmlBody) {
+                const { contentType, body: mp } = buildMultipartAlternative(body, htmlBody);
+                headers.push(`Content-Type: ${contentType}`);
+                bodyText = mp;
+            }
+            else {
+                headers.push('Content-Type: text/plain; charset="UTF-8"');
+                headers.push('Content-Transfer-Encoding: 8bit');
+                bodyText = normalizeBodyLineEndings(body);
+            }
             if (cc)
                 headers.push(`Cc: ${encodeAddressHeader(cc)}`);
             if (replyToMessageId) {
                 headers.push(`In-Reply-To: ${replyToMessageId}`);
                 headers.push(`References: ${replyToMessageId}`);
             }
-            const rawMessage = [...headers, '', normalizeBodyLineEndings(body)].join('\r\n');
+            const rawMessage = [...headers, '', bodyText].join('\r\n');
             const encoded = Buffer.from(rawMessage, 'utf-8').toString('base64url');
             const sendParams = {
                 userId: 'me',
@@ -249,12 +260,14 @@ export function registerGmailTools(server) {
             account: accountEnum.describe('Google account alias'),
             to: z.string().describe('Recipient(s), comma-separated'),
             subject: z.string().describe('Email subject'),
-            body: z.string().describe('Plain text body'),
+            body: z.string().describe('Plain text body (always required; also used as fallback when htmlBody is set)'),
+            htmlBody: z.string().optional()
+                .describe('Optional HTML body. When set, drafts as multipart/alternative so HTML-capable clients render the rich version. Use bare tags only: <p>, <a>, <br>, <strong>, <em>, <ul><li>.'),
             cc: z.string().optional().describe('CC recipients, comma-separated'),
             replyToThreadId: z.string().optional()
                 .describe('Thread ID to associate the draft with'),
         },
-    }, async ({ account, to, subject, body, cc, replyToThreadId }) => {
+    }, async ({ account, to, subject, body, htmlBody, cc, replyToThreadId }) => {
         try {
             const auth = await getClient(account);
             const gmail = google.gmail({ version: 'v1', auth });
@@ -264,12 +277,21 @@ export function registerGmailTools(server) {
                 `To: ${encodeAddressHeader(to)}`,
                 `Subject: ${encodeHeaderValue(subject)}`,
                 'MIME-Version: 1.0',
-                'Content-Type: text/plain; charset="UTF-8"',
-                'Content-Transfer-Encoding: 8bit',
             ];
+            let bodyText;
+            if (htmlBody) {
+                const { contentType, body: mp } = buildMultipartAlternative(body, htmlBody);
+                headers.push(`Content-Type: ${contentType}`);
+                bodyText = mp;
+            }
+            else {
+                headers.push('Content-Type: text/plain; charset="UTF-8"');
+                headers.push('Content-Transfer-Encoding: 8bit');
+                bodyText = normalizeBodyLineEndings(body);
+            }
             if (cc)
                 headers.push(`Cc: ${encodeAddressHeader(cc)}`);
-            const rawMessage = [...headers, '', normalizeBodyLineEndings(body)].join('\r\n');
+            const rawMessage = [...headers, '', bodyText].join('\r\n');
             const encoded = Buffer.from(rawMessage, 'utf-8').toString('base64url');
             const draftParams = {
                 userId: 'me',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-google-multi",
-  "version": "4.3.0-alpha.1",
+  "version": "4.3.0-alpha.3",
   "description": "MCP server for Gmail, Google Drive, Calendar, Sheets, Docs, and Contacts with multi-account support",
   "type": "module",
   "license": "MIT",
@@ -44,6 +44,7 @@
     "prepublishOnly": "npm run build",
     "watch": "tsc --watch",
     "auth": "node dist/index.js auth --account",
+    "migrate-tokens": "node dist/index.js migrate-tokens",
     "lint": "eslint .",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
@@ -67,6 +68,6 @@
     "semantic-release": "^25.0.3",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.59.1",
-    "vitest": "^4.1.5"
+    "vitest": "^3.2.4"
   }
 }