google-tools-mcp 1.0.0 → 1.0.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Karthik Senthil
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# google-tools-mcp
+
+A unified MCP server for Google Workspace — Drive, Docs, Sheets, Gmail, and Calendar — with **146 tools** across 8 categories.
+
+All tools are loaded at startup so they're immediately available to your AI agent. No discovery step needed.
+
+## Why This Exists
+
+Most Google MCP servers split functionality across separate packages. This server combines everything into one — single auth token, single process, single config.
+
+## Features
+
+- **146 tools** across 8 categories, all available immediately
+- **Single auth token** — one OAuth flow covers Drive, Docs, Sheets, Gmail, and Calendar
+- **Lazy-loading auth** — no browser popup until your first tool call
+- **Multi-profile support** — separate tokens per Google account
+- **No telemetry**
+
+## Getting Started
+
+### Step 1: Create Google OAuth Credentials
+
+1. Go to the [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a project (or use an existing one)
+3. Enable the **Google Docs API**, **Google Sheets API**, **Google Drive API**, **Gmail API**, and **Google Calendar API**
+4. Go to **Credentials** → **Create Credentials** → **OAuth Client ID**
+5. Select **Desktop application** as the application type
+6. Download the credentials or note your **Client ID** and **Client Secret**
+
+### Step 2: Provide Your Credentials
+
+Choose **one** of the following methods (whichever you prefer):
+
+#### Option A: Use `credentials.json`
+
+Download the JSON file from Google Cloud Console and place it in either location:
+
+```
+~/.config/google-tools-mcp/credentials.json   (recommended — shared across projects)
+./credentials.json                              (local to your project)
+```
+
+That's it — no env vars needed. The server will find it automatically.
+
+#### Option B: Create a `.env` file
+
+Create a `.env` file in either location:
+
+```
+~/.config/google-tools-mcp/.env   (recommended — shared across projects)
+./.env                             (local to your project)
+```
+
+With the following contents:
+
+```env
+GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
+GOOGLE_CLIENT_SECRET=your-client-secret
+```
+
+#### Option C: Set env vars in your MCP config
+
+Add the credentials directly to your MCP configuration:
+
+```json
+{
+  "mcpServers": {
+    "google": {
+      "command": "npx",
+      "args": ["-y", "google-tools-mcp"],
+      "env": {
+        "GOOGLE_CLIENT_ID": "your-client-id",
+        "GOOGLE_CLIENT_SECRET": "your-client-secret"
+      }
+    }
+  }
+}
+```
+
+> **Credential lookup order:** env vars → `~/.config/google-tools-mcp/.env` → project root `.env` → `~/.config/google-tools-mcp/credentials.json` → project root `credentials.json`
+
+### Step 3: Add to Your MCP Client
+
+#### Claude Code (recommended)
+
+If you used Option A or B above:
+
+```bash
+claude mcp add google -- npx -y google-tools-mcp
+```
+
+Or with env vars (Option C):
+
+```bash
+claude mcp add google \
+  -e GOOGLE_CLIENT_ID=your-client-id \
+  -e GOOGLE_CLIENT_SECRET=your-client-secret \
+  -- npx -y google-tools-mcp
+```
+
+#### Project-Local Installation (with profile)
+
+Via the `claude` CLI:
+
+```bash
+claude mcp add google \
+  -e GOOGLE_MCP_PROFILE=myprofile \
+  -- npx -y google-tools-mcp
+```
+
+Or manually in your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "google": {
+      "command": "npx",
+      "args": ["-y", "google-tools-mcp"],
+      "env": {
+        "GOOGLE_MCP_PROFILE": "myprofile"
+      }
+    }
+  }
+}
+```
+
+#### Other MCP clients
+
+Add this to your MCP configuration (e.g., `.mcp.json`, `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "google": {
+      "command": "npx",
+      "args": ["-y", "google-tools-mcp"]
+    }
+  }
+}
+```
+
+If using Option C, add an `"env"` block with your `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`.
+
+### Step 4: Authenticate
+
+On your first tool call, the server will automatically open your browser for Google OAuth consent. Sign in and grant access — the token is saved to `~/.config/google-tools-mcp/token.json` for future use.
+
+You can also run the auth flow manually anytime:
+
+```bash
+npx google-tools-mcp auth
+```
+
+### Multi-Account Support
+
+Set the `GOOGLE_MCP_PROFILE` env var to use separate tokens per profile:
+
+```json
+{
+  "env": {
+    "GOOGLE_MCP_PROFILE": "work"
+  }
+}
+```
+
+This stores tokens in `~/.config/google-tools-mcp/work/` instead of the default directory.
+
+## Tool Categories
+
+### `files` (16 tools)
+Google Drive file management and content reading.
+
+`listDocuments`, `searchDocuments`, `getDocumentInfo`, `createFolder`, `listFolderContents`, `getFolderInfo`, `moveFile`, `copyFile`, `renameFile`, `deleteFile`, `createDocument`, `createDocumentFromTemplate`, `listSharedDrives`, `listSharedWithMe`, `readFile`, `searchFileContents`
+
+### `documents` (23 tools)
+Google Docs read/write/format with markdown support.
+
+`readDocument`, `appendText`, `insertText`, `deleteRange`, `modifyText`, `findAndReplace`, `insertTable`, `insertTableWithData`, `insertPageBreak`, `insertImage`, `listTabs`, `addTab`, `renameTab`, `applyTextStyle`, `applyParagraphStyle`, `addComment`, `deleteComment`, `getComment`, `listComments`, `replyToComment`, `resolveComment`, `appendMarkdown`, `replaceDocumentWithMarkdown`
+
+### `spreadsheets` (30 tools)
+Google Sheets operations.
+
+`readSpreadsheet`, `writeSpreadsheet`, `batchWrite`, `appendRows`, `clearRange`, `createSpreadsheet`, `getSpreadsheetInfo`, `addSheet`, `deleteSheet`, `duplicateSheet`, `renameSheet`, `formatCells`, `readCellFormat`, `autoResizeColumns`, `freezeRowsAndColumns`, `setColumnWidths`, `addConditionalFormatting`, `copyFormatting`, `setDropdownValidation`, `createTable`, `deleteTable`, `getTable`, `listTables`, `appendTableRows`, `updateTableRange`, `insertChart`, `deleteChart`, `groupRows`, `ungroupAllRows`, `listSpreadsheets`
+
+### `email` (19 tools)
+Gmail messages and drafts.
+
+`send_message`, `reply_message`, `forward_message`, `get_message`, `list_messages`, `modify_message`, `delete_message`, `trash_message`, `untrash_message`, `batch_delete_messages`, `batch_modify_messages`, `batch_get_messages`, `get_attachment`, `create_draft`, `update_draft`, `delete_draft`, `get_draft`, `list_drafts`, `send_draft`
+
+### `email_threads` (7 tools)
+Gmail thread-level operations.
+
+`get_thread`, `list_threads`, `batch_get_threads`, `modify_thread`, `delete_thread`, `trash_thread`, `untrash_thread`
+
+### `email_labels` (6 tools)
+Gmail label management.
+
+`create_label`, `delete_label`, `get_label`, `list_labels`, `patch_label`, `update_label`
+
+### `email_settings` (37 tools)
+Gmail admin and configuration.
+
+`get_auto_forwarding`, `update_auto_forwarding`, `get_imap`, `update_imap`, `get_language`, `update_language`, `get_pop`, `update_pop`, `get_vacation`, `update_vacation`, `add_delegate`, `remove_delegate`, `get_delegate`, `list_delegates`, `create_filter`, `delete_filter`, `get_filter`, `list_filters`, `create_forwarding_address`, `delete_forwarding_address`, `get_forwarding_address`, `list_forwarding_addresses`, `create_send_as`, `delete_send_as`, `get_send_as`, `list_send_as`, `patch_send_as`, `update_send_as`, `verify_send_as`, `delete_smime_info`, `get_smime_info`, `insert_smime_info`, `list_smime_info`, `set_default_smime_info`, `get_profile`, `watch_mailbox`, `stop_mail_watch`
+
+### `calendar` (8 tools)
+Google Calendar — events, availability, and calendar management.
+
+`list_calendars`, `get_events`, `manage_event`, `get_busy`, `get_free`, `move_event`, `list_recurring_event_instances`, `manage_calendar`
+
+## Environment Variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `GOOGLE_CLIENT_ID` | No* | OAuth 2.0 Client ID |
+| `GOOGLE_CLIENT_SECRET` | No* | OAuth 2.0 Client Secret |
+| `GOOGLE_MCP_PROFILE` | No | Profile name for multi-account support (see above) |
+| `LOG_LEVEL` | No | `debug`, `info`, `warn`, `error`, or `silent` |
+| `SERVICE_ACCOUNT_PATH` | No | Path to service account JSON key (alternative to OAuth) |
+| `GOOGLE_IMPERSONATE_USER` | No | Email to impersonate with service account |
+
+\* Not required as env vars if you provide credentials via `.env` file or `credentials.json` (see [Step 2](#step-2-provide-your-credentials)).
+
+## Migrating from gdrive-tools-mcp / gmail-tools-mcp
+
+This package replaces both [`gdrive-tools-mcp`](https://www.npmjs.com/package/gdrive-tools-mcp) and [`gmail-tools-mcp`](https://www.npmjs.com/package/gmail-tools-mcp). To migrate:
+
+1. Replace both MCP server entries with a single `google-tools-mcp` entry
+2. Re-authenticate (the combined server uses its own config dir at `~/.config/google-tools-mcp/`)
+3. All tools are available immediately — no discovery step needed
+
+## License
+
+MIT

package/dist/auth.js

@@ -46,6 +46,8 @@ const SCOPES = [
     'https://www.googleapis.com/auth/gmail.send',
     'https://www.googleapis.com/auth/gmail.settings.basic',
     'https://www.googleapis.com/auth/gmail.settings.sharing',
+    // Calendar
+    'https://www.googleapis.com/auth/calendar',
 ];
 
 // ---------------------------------------------------------------------------

package/dist/clients.js

@@ -11,6 +11,7 @@ let googleDrive = null;
 let googleSheets = null;
 let googleScript = null;
 let gmailClient = null;
+let calendarClient = null;
 
 async function ensureAuth() {
     if (authClient) return;
@@ -49,6 +50,14 @@ export async function initializeGmailClient() {
     return { authClient, gmailClient };
 }
 
+// --- Calendar client ---
+export async function initializeCalendarClient() {
+    if (calendarClient) return { authClient, calendarClient };
+    await ensureAuth();
+    if (!calendarClient) calendarClient = google.calendar({ version: 'v3', auth: authClient });
+    return { authClient, calendarClient };
+}
+
 // --- Reset all clients (used by logout) ---
 export function resetClients() {
     authClient = null;
@@ -57,6 +66,7 @@ export function resetClients() {
     googleSheets = null;
     googleScript = null;
     gmailClient = null;
+    calendarClient = null;
 }
 
 // --- Individual client getters ---
@@ -95,3 +105,9 @@ export async function getGmailClient() {
     if (!gmail) throw new UserError('Gmail client is not initialized.');
     return gmail;
 }
+
+export async function getCalendarClient() {
+    const { calendarClient: calendar } = await initializeCalendarClient();
+    if (!calendar) throw new UserError('Google Calendar client is not initialized.');
+    return calendar;
+}

package/dist/index.js

@@ -1,14 +1,13 @@
 #!/usr/bin/env node
 // google-tools-mcp — Combined Google Workspace MCP server
 //
-// Provides lazy-loaded tool categories for Drive, Docs, Sheets, and Gmail.
-// Only a discovery tool is exposed at startup; individual tools are loaded on demand.
+// All tool categories (Drive, Docs, Sheets, Gmail, Calendar) are loaded at
+// startup so they're available in the initial tools/list response.
 //
 // Usage:
 //   google-tools-mcp          Start the MCP server (default)
 //   google-tools-mcp auth     Run the interactive OAuth flow
 import { FastMCP } from 'fastmcp';
-import { collectToolsWhileRegistering, installCachedToolsListHandler } from './cachedToolsList.js';
 import { registerAllTools } from './tools/index.js';
 import { logger } from './logger.js';
 
@@ -38,17 +37,13 @@ const server = new FastMCP({
     version: '1.0.0',
 });
 
-const registeredTools = [];
-collectToolsWhileRegistering(server, registeredTools);
-registerAllTools(server);
+await registerAllTools(server);
 
 try {
     logger.info('Starting google-tools-mcp server...');
     await server.start({ transportType: 'stdio' });
-    installCachedToolsListHandler(server, registeredTools);
     logger.info('MCP Server running using stdio. Awaiting client connection...');
     logger.info('Google auth will run automatically on first tool call.');
-    logger.info(`${registeredTools.length} tools registered at startup (discovery + logout). Call load_google_tools to load more.`);
 } catch (startError) {
     logger.error('FATAL: Server failed to start:', startError.message || startError);
     process.exit(1);

package/dist/tools/calendar/getBusy.js

@@ -0,0 +1,64 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getCalendarClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'get_busy',
+        description:
+            'Returns busy time blocks for one or more people in a given time range. ' +
+            'Works across your Google Workspace org without needing calendar sharing — you see when people are busy but not event details. ' +
+            'Pass email addresses as calendar_ids to check other people.',
+        parameters: z.object({
+            time_min: z
+                .string()
+                .describe('Start of query range in RFC3339 format (e.g. "2025-03-15T00:00:00Z").'),
+            time_max: z
+                .string()
+                .describe('End of query range in RFC3339 format (e.g. "2025-03-16T23:59:59Z").'),
+            calendar_ids: z
+                .array(z.string())
+                .optional()
+                .default(['primary'])
+                .describe('Calendar IDs or email addresses to check. Defaults to ["primary"].'),
+        }),
+        execute: async (args, { log }) => {
+            const calendar = await getCalendarClient();
+            log.info(`Checking busy times for ${args.calendar_ids.join(', ')}`);
+
+            try {
+                const response = await calendar.freebusy.query({
+                    requestBody: {
+                        timeMin: args.time_min,
+                        timeMax: args.time_max,
+                        items: args.calendar_ids.map((id) => ({ id })),
+                    },
+                });
+
+                const calendars = response.data.calendars || {};
+                const results = {};
+
+                for (const [calId, data] of Object.entries(calendars)) {
+                    if (data.errors?.length) {
+                        results[calId] = {
+                            error: data.errors[0].reason,
+                            busy: [],
+                        };
+                    } else {
+                        results[calId] = {
+                            busy: (data.busy || []).map((block) => ({
+                                start: block.start,
+                                end: block.end,
+                            })),
+                        };
+                    }
+                }
+
+                return JSON.stringify(results, null, 2);
+            } catch (error) {
+                log.error(`Error querying freebusy: ${error.message || error}`);
+                throw new UserError(`Failed to query busy times: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}

package/dist/tools/calendar/getEvents.js

@@ -0,0 +1,140 @@
+import { UserError } from 'fastmcp';
+import { z } from 'zod';
+import { getCalendarClient } from '../../clients.js';
+
+export function register(server) {
+    server.addTool({
+        name: 'get_events',
+        description:
+            'Retrieves events from a Google Calendar. Can get a single event by ID, or list events in a time range with optional search. ' +
+            'Use calendar_id to query another user\'s calendar (requires sharing) or "primary" for the authenticated user.',
+        parameters: z.object({
+            calendar_id: z
+                .string()
+                .optional()
+                .default('primary')
+                .describe('Calendar ID to query. Use "primary" for the main calendar, or an email address for a shared calendar.'),
+            event_id: z
+                .string()
+                .optional()
+                .describe('Specific event ID to retrieve. If provided, other filter params are ignored.'),
+            time_min: z
+                .string()
+                .optional()
+                .describe('Start of time range in RFC3339 format (e.g. "2025-01-01T00:00:00Z"). Defaults to now if not specified.'),
+            time_max: z
+                .string()
+                .optional()
+                .describe('End of time range in RFC3339 format (e.g. "2025-01-31T23:59:59Z").'),
+            max_results: z
+                .number()
+                .optional()
+                .default(25)
+                .describe('Maximum number of events to return (default 25, max 2500).'),
+            query: z
+                .string()
+                .optional()
+                .describe('Free-text search across event summary, description, location, attendees, etc.'),
+            detailed: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe('If true, includes attendees, attachments, conferencing details, and extended properties.'),
+        }),
+        execute: async (args, { log }) => {
+            const calendar = await getCalendarClient();
+
+            try {
+                // Single event fetch
+                if (args.event_id) {
+                    log.info(`Getting event ${args.event_id} from calendar ${args.calendar_id}`);
+                    const response = await calendar.events.get({
+                        calendarId: args.calendar_id,
+                        eventId: args.event_id,
+                    });
+                    return JSON.stringify(formatEvent(response.data, true), null, 2);
+                }
+
+                // List events
+                log.info(`Listing events from calendar ${args.calendar_id}`);
+                const params = {
+                    calendarId: args.calendar_id,
+                    maxResults: Math.min(args.max_results, 2500),
+                    singleEvents: true,
+                    orderBy: 'startTime',
+                };
+
+                if (args.time_min) params.timeMin = args.time_min;
+                else params.timeMin = new Date().toISOString();
+
+                if (args.time_max) params.timeMax = args.time_max;
+                if (args.query) params.q = args.query;
+
+                const response = await calendar.events.list(params);
+                const events = response.data.items || [];
+
+                return JSON.stringify(
+                    events.map((e) => formatEvent(e, args.detailed)),
+                    null,
+                    2
+                );
+            } catch (error) {
+                log.error(`Error getting events: ${error.message || error}`);
+                if (error.code === 404)
+                    throw new UserError('Calendar or event not found. Check the calendar_id or event_id.');
+                if (error.code === 403)
+                    throw new UserError('Permission denied. The calendar may not be shared with you.');
+                throw new UserError(`Failed to get events: ${error.message || 'Unknown error'}`);
+            }
+        },
+    });
+}
+
+function formatEvent(event, detailed) {
+    const result = {
+        id: event.id,
+        summary: event.summary || '(No title)',
+        start: event.start?.dateTime || event.start?.date || null,
+        end: event.end?.dateTime || event.end?.date || null,
+        status: event.status,
+        htmlLink: event.htmlLink,
+    };
+
+    if (event.location) result.location = event.location;
+    if (event.description) result.description = event.description;
+    if (event.recurringEventId) result.recurringEventId = event.recurringEventId;
+
+    if (detailed) {
+        if (event.attendees?.length) {
+            result.attendees = event.attendees.map((a) => ({
+                email: a.email,
+                displayName: a.displayName || null,
+                responseStatus: a.responseStatus,
+                organizer: a.organizer || false,
+                self: a.self || false,
+            }));
+        }
+        if (event.conferenceData) {
+            const entryPoints = event.conferenceData.entryPoints || [];
+            result.conferencing = entryPoints.map((ep) => ({
+                type: ep.entryPointType,
+                uri: ep.uri,
+                label: ep.label || null,
+            }));
+        }
+        if (event.attachments?.length) {
+            result.attachments = event.attachments.map((a) => ({
+                title: a.title,
+                fileUrl: a.fileUrl,
+                mimeType: a.mimeType,
+            }));
+        }
+        if (event.creator) result.creator = event.creator;
+        if (event.organizer) result.organizer = { email: event.organizer.email, displayName: event.organizer.displayName || null };
+        result.visibility = event.visibility || 'default';
+        result.transparency = event.transparency || 'opaque';
+        if (event.reminders) result.reminders = event.reminders;
+    }
+
+    return result;
+}