gmail-workspace-mcp-server 0.0.3 → 0.0.4

package/README.md

@@ -4,8 +4,12 @@ An MCP (Model Context Protocol) server that provides Gmail integration for AI as
 
 ## Features
 
-- **List Recent Emails**: Retrieve recent emails within a specified time horizon
+- **List Email Conversations**: Retrieve emails with label filtering
 - **Get Email Details**: Fetch full email content including body and attachments info
+- **Search Emails**: Search using Gmail's powerful query syntax
+- **Manage Emails**: Mark as read/unread, star/unstar, archive, apply labels
+- **Create Drafts**: Compose draft emails with reply support
+- **Send Emails**: Send new emails or replies, directly or from drafts
 - **Service Account Authentication**: Secure domain-wide delegation for Google Workspace organizations
 
 ## Installation
@@ -30,19 +34,49 @@ This server requires a Google Cloud service account with domain-wide delegation
 2. Create or select a project
 3. Enable the Gmail API
 4. Create a service account with domain-wide delegation enabled
-5. In [Google Workspace Admin Console](https://admin.google.com/), grant the service account access to the `https://www.googleapis.com/auth/gmail.readonly` scope
+5. In [Google Workspace Admin Console](https://admin.google.com/), grant the service account access to the following scopes:
+   - `https://www.googleapis.com/auth/gmail.readonly` (read emails)
+   - `https://www.googleapis.com/auth/gmail.modify` (modify labels)
+   - `https://www.googleapis.com/auth/gmail.compose` (create drafts)
+   - `https://www.googleapis.com/auth/gmail.send` (send emails)
 6. Download the JSON key file
 
 ### Environment Variables
 
-| Variable                             | Required | Description                              |
-| ------------------------------------ | -------- | ---------------------------------------- |
-| `GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL` | Yes      | Service account email address            |
-| `GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY`  | Yes      | Service account private key (PEM format) |
-| `GMAIL_IMPERSONATE_EMAIL`            | Yes      | Email address to impersonate             |
+| Variable                             | Required | Description                                                         |
+| ------------------------------------ | -------- | ------------------------------------------------------------------- |
+| `GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL` | Yes      | Service account email address                                       |
+| `GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY`  | Yes      | Service account private key (PEM format)                            |
+| `GMAIL_IMPERSONATE_EMAIL`            | Yes      | Email address to impersonate                                        |
+| `GMAIL_ENABLED_TOOLGROUPS`           | No       | Comma-separated list of tool groups to enable (default: all groups) |
 
 You can find the `client_email` and `private_key` values in your service account JSON key file.
 
+### Tool Groups
+
+The server supports three tool groups for permission-based access control:
+
+| Group                | Tools Included                                                                     | Risk Level |
+| -------------------- | ---------------------------------------------------------------------------------- | ---------- |
+| `readonly`           | `list_email_conversations`, `get_email_conversation`, `search_email_conversations` | Low        |
+| `readwrite`          | All readonly tools + `change_email_conversation`, `draft_email`                    | Medium     |
+| `readwrite_external` | All readwrite tools + `send_email`                                                 | High       |
+
+By default, all tool groups are enabled. To restrict access, set the `GMAIL_ENABLED_TOOLGROUPS` environment variable:
+
+```bash
+# Read-only access (no write/send capabilities)
+GMAIL_ENABLED_TOOLGROUPS=readonly
+
+# Read and write, but no external sending
+GMAIL_ENABLED_TOOLGROUPS=readwrite
+
+# Full access including sending emails (default)
+GMAIL_ENABLED_TOOLGROUPS=readwrite_external
+```
+
+**Security Note:** The `send_email` tool is in a separate `readwrite_external` group because it can send emails externally, which carries higher risk than internal operations like modifying labels or creating drafts.
+
 ## Configuration
 
 ### Claude Desktop
@@ -72,27 +106,30 @@ Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/
 
 ## Available Tools
 
-### gmail_list_recent_emails
+### list_email_conversations
 
-List recent emails from Gmail within a specified time horizon.
+List email conversations from Gmail with optional filtering.
 
 **Parameters:**
 
-- `hours` (number, optional): Time horizon in hours (default: 24)
-- `labels` (string, optional): Comma-separated label IDs (default: "INBOX")
-- `max_results` (number, optional): Maximum emails to return (default: 10, max: 100)
+- `count` (number, optional): Number of emails to return (default: 10, max: 100)
+- `labels` (string, optional): Comma-separated label IDs to filter by (default: "INBOX")
+- `sort_by` (string, optional): Sort order - "recent" (newest first) or "oldest" (default: recent)
+- `after` (string, optional): Only return emails after this datetime, exclusive (ISO 8601 UTC, e.g., "2024-01-15T14:30:00Z")
+- `before` (string, optional): Only return emails before this datetime, exclusive (ISO 8601 UTC, e.g., "2024-01-15T14:30:00Z")
 
 **Example:**
 
 ```json
 {
-  "hours": 48,
+  "count": 20,
   "labels": "INBOX,STARRED",
-  "max_results": 20
+  "after": "2024-01-15T00:00:00Z",
+  "before": "2024-01-20T23:59:59Z"
 }
 ```
 
-### gmail_get_email
+### get_email_conversation
 
 Retrieve the full content of a specific email by its ID.
 
@@ -108,6 +145,99 @@ Retrieve the full content of a specific email by its ID.
 }
 ```
 
+### search_email_conversations
+
+Search emails using Gmail's powerful query syntax.
+
+**Parameters:**
+
+- `query` (string, required): Gmail search query (e.g., "from:user@example.com", "is:unread", "subject:meeting")
+- `count` (number, optional): Maximum results to return (default: 10, max: 100)
+
+**Example:**
+
+```json
+{
+  "query": "from:alice@example.com is:unread",
+  "count": 20
+}
+```
+
+### change_email_conversation
+
+Modify email labels and status (read/unread, starred, archived).
+
+**Parameters:**
+
+- `email_id` (string, required): The email ID to modify
+- `status` (string, optional): "read", "unread", or "archived"
+- `is_starred` (boolean, optional): Star or unstar the email
+- `labels` (string, optional): Comma-separated labels to add
+- `remove_labels` (string, optional): Comma-separated labels to remove
+
+**Example:**
+
+```json
+{
+  "email_id": "18abc123def456",
+  "status": "read",
+  "is_starred": true
+}
+```
+
+### draft_email
+
+Create a draft email, optionally as a reply to an existing conversation.
+
+**Parameters:**
+
+- `to` (string, required): Recipient email address
+- `subject` (string, required): Email subject
+- `body` (string, required): Email body (plain text)
+- `thread_id` (string, optional): Thread ID for replies
+- `reply_to_email_id` (string, optional): Email ID to reply to (sets References/In-Reply-To headers)
+
+**Example:**
+
+```json
+{
+  "to": "recipient@example.com",
+  "subject": "Meeting Follow-up",
+  "body": "Thanks for the meeting today!"
+}
+```
+
+### send_email
+
+Send an email directly or from an existing draft.
+
+**Parameters:**
+
+- `to` (string, conditional): Recipient email (required unless sending from draft)
+- `subject` (string, conditional): Email subject (required unless sending from draft)
+- `body` (string, conditional): Email body (required unless sending from draft)
+- `from_draft_id` (string, optional): Send an existing draft by ID
+- `thread_id` (string, optional): Thread ID for replies
+- `reply_to_email_id` (string, optional): Email ID to reply to
+
+**Example (new email):**
+
+```json
+{
+  "to": "recipient@example.com",
+  "subject": "Hello",
+  "body": "This is a test email."
+}
+```
+
+**Example (send draft):**
+
+```json
+{
+  "from_draft_id": "r123456789"
+}
+```
+
 ## Development
 
 ### Setup

package/build/index.integration-with-mock.js

@@ -4,11 +4,16 @@
  * Used for running integration tests without real Gmail API access
  */
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { createMCPServer } from '../shared/index.js';
 import { logServerStart, logError } from '../shared/logging.js';
-// =============================================================================
-// MOCK DATA
-// =============================================================================
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
 const MOCK_EMAILS = [
     {
         id: 'msg_001',
@@ -24,6 +29,7 @@ const MOCK_EMAILS = [
                 { name: 'From', value: 'alice@example.com' },
                 { name: 'To', value: 'me@example.com' },
                 { name: 'Date', value: new Date(Date.now() - 1000 * 60 * 30).toISOString() },
+                { name: 'Message-ID', value: '<msg001@example.com>' },
             ],
             body: {
                 size: 150,
@@ -46,6 +52,7 @@ const MOCK_EMAILS = [
                 { name: 'From', value: 'calendar@example.com' },
                 { name: 'To', value: 'me@example.com' },
                 { name: 'Date', value: new Date(Date.now() - 1000 * 60 * 60 * 2).toISOString() },
+                { name: 'Message-ID', value: '<msg002@example.com>' },
             ],
             body: {
                 size: 200,
@@ -55,6 +62,9 @@ const MOCK_EMAILS = [
         sizeEstimate: 2048,
     },
 ];
+const mockDrafts = [];
+let draftIdCounter = 1;
+let messageIdCounter = 100;
 // =============================================================================
 // MOCK CLIENT
 // =============================================================================
@@ -66,6 +76,17 @@ function createMockClient() {
             if (options?.labelIds && options.labelIds.length > 0) {
                 filtered = MOCK_EMAILS.filter((email) => options.labelIds.some((label) => email.labelIds?.includes(label)));
             }
+            // Handle query search
+            if (options?.q) {
+                const query = options.q.toLowerCase();
+                filtered = filtered.filter((email) => {
+                    const subject = email.payload?.headers?.find((h) => h.name === 'Subject')?.value?.toLowerCase() || '';
+                    const from = email.payload?.headers?.find((h) => h.name === 'From')?.value?.toLowerCase() || '';
+                    return (subject.includes(query) ||
+                        from.includes(query) ||
+                        email.snippet.toLowerCase().includes(query));
+                });
+            }
             // Apply maxResults
             const maxResults = options?.maxResults ?? 10;
             const messages = filtered.slice(0, maxResults).map((e) => ({
@@ -84,6 +105,121 @@ function createMockClient() {
             }
             return email;
         },
+        async modifyMessage(messageId, options) {
+            const email = MOCK_EMAILS.find((e) => e.id === messageId);
+            if (!email) {
+                throw new Error(`Message not found: ${messageId}`);
+            }
+            // Apply label changes
+            let labels = [...(email.labelIds || [])];
+            if (options.removeLabelIds) {
+                labels = labels.filter((l) => !options.removeLabelIds.includes(l));
+            }
+            if (options.addLabelIds) {
+                for (const label of options.addLabelIds) {
+                    if (!labels.includes(label)) {
+                        labels.push(label);
+                    }
+                }
+            }
+            // Update the email in the mock array
+            email.labelIds = labels;
+            return { ...email, labelIds: labels };
+        },
+        async createDraft(options) {
+            const draft = {
+                id: `draft_${draftIdCounter++}`,
+                message: {
+                    id: `msg_${messageIdCounter++}`,
+                    threadId: options.threadId || `thread_${messageIdCounter}`,
+                    labelIds: ['DRAFT'],
+                    snippet: options.body.substring(0, 100),
+                    historyId: '12347',
+                    internalDate: String(Date.now()),
+                    payload: {
+                        mimeType: 'text/plain',
+                        headers: [
+                            { name: 'Subject', value: options.subject },
+                            { name: 'From', value: 'me@example.com' },
+                            { name: 'To', value: options.to },
+                            { name: 'Date', value: new Date().toISOString() },
+                        ],
+                        body: {
+                            size: options.body.length,
+                            data: Buffer.from(options.body).toString('base64url'),
+                        },
+                    },
+                },
+            };
+            mockDrafts.push(draft);
+            return draft;
+        },
+        async getDraft(draftId) {
+            const draft = mockDrafts.find((d) => d.id === draftId);
+            if (!draft) {
+                throw new Error(`Draft not found: ${draftId}`);
+            }
+            return draft;
+        },
+        async listDrafts(options) {
+            const maxResults = options?.maxResults ?? 10;
+            const drafts = mockDrafts.slice(0, maxResults).map((d) => ({
+                id: d.id,
+                message: {
+                    id: d.message.id,
+                    threadId: d.message.threadId,
+                },
+            }));
+            return {
+                drafts,
+                resultSizeEstimate: drafts.length,
+            };
+        },
+        async deleteDraft(draftId) {
+            const index = mockDrafts.findIndex((d) => d.id === draftId);
+            if (index === -1) {
+                throw new Error(`Draft not found: ${draftId}`);
+            }
+            mockDrafts.splice(index, 1);
+        },
+        async sendMessage(options) {
+            const sentMessage = {
+                id: `msg_${messageIdCounter++}`,
+                threadId: options.threadId || `thread_${messageIdCounter}`,
+                labelIds: ['SENT'],
+                snippet: options.body.substring(0, 100),
+                historyId: '12348',
+                internalDate: String(Date.now()),
+                payload: {
+                    mimeType: 'text/plain',
+                    headers: [
+                        { name: 'Subject', value: options.subject },
+                        { name: 'From', value: 'me@example.com' },
+                        { name: 'To', value: options.to },
+                        { name: 'Date', value: new Date().toISOString() },
+                    ],
+                    body: {
+                        size: options.body.length,
+                        data: Buffer.from(options.body).toString('base64url'),
+                    },
+                },
+            };
+            return sentMessage;
+        },
+        async sendDraft(draftId) {
+            const draft = mockDrafts.find((d) => d.id === draftId);
+            if (!draft) {
+                throw new Error(`Draft not found: ${draftId}`);
+            }
+            // Remove from drafts
+            const index = mockDrafts.findIndex((d) => d.id === draftId);
+            mockDrafts.splice(index, 1);
+            // Return the message with SENT label
+            return {
+                ...draft.message,
+                labelIds: ['SENT'],
+            };
+        },
     };
 }
 // =============================================================================
@@ -91,7 +227,7 @@ function createMockClient() {
 // =============================================================================
 async function main() {
     // Create server with mock client
-    const { server, registerHandlers } = createMCPServer();
+    const { server, registerHandlers } = createMCPServer({ version: VERSION });
     // Register handlers with mock client factory
     await registerHandlers(server, createMockClient);
     // Start server with stdio transport

package/build/index.js

@@ -1,7 +1,15 @@
 #!/usr/bin/env node
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
 import { createMCPServer } from '../shared/index.js';
-import { logServerStart, logError } from '../shared/logging.js';
+import { logServerStart, logError, logWarning } from '../shared/logging.js';
+// Read version from package.json
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageJsonPath = join(__dirname, '..', 'package.json');
+const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+const VERSION = packageJson.version;
 // =============================================================================
 // ENVIRONMENT VALIDATION
 // =============================================================================
@@ -30,8 +38,13 @@ function validateEnvironment() {
         console.error('\nSetup steps:');
         console.error('  1. Go to https://console.cloud.google.com/');
         console.error('  2. Create a service account with domain-wide delegation');
-        console.error('  3. In Google Workspace Admin, grant gmail.readonly scope');
+        console.error('  3. In Google Workspace Admin, grant required Gmail API scopes');
         console.error('  4. Download the JSON key file and extract client_email and private_key');
+        console.error('\nOptional environment variables:');
+        console.error('  GMAIL_ENABLED_TOOLGROUPS: Comma-separated list of tool groups to enable');
+        console.error('    Valid groups: readonly, readwrite, readwrite_external');
+        console.error('    Default: all groups enabled');
+        console.error('    Example: GMAIL_ENABLED_TOOLGROUPS=readwrite');
         console.error('\n======================================================\n');
         process.exit(1);
     }
@@ -42,11 +55,15 @@ function validateEnvironment() {
 async function main() {
     // Step 1: Validate environment variables
     validateEnvironment();
-    // Step 2: Create server using factory
-    const { server, registerHandlers } = createMCPServer();
-    // Step 3: Register all handlers (tools)
+    // Step 2: Log tool groups if configured
+    if (process.env.GMAIL_ENABLED_TOOLGROUPS) {
+        logWarning('config', `Enabled tool groups: ${process.env.GMAIL_ENABLED_TOOLGROUPS}`);
+    }
+    // Step 3: Create server using factory
+    const { server, registerHandlers } = createMCPServer({ version: VERSION });
+    // Step 4: Register all handlers (tools)
     await registerHandlers(server);
-    // Step 4: Start server with stdio transport
+    // Step 5: Start server with stdio transport
     const transport = new StdioServerTransport();
     await server.connect(transport);
     logServerStart('Gmail');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gmail-workspace-mcp-server",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "MCP server for Gmail integration with service account support",
   "main": "build/index.js",
   "type": "module",

package/shared/gmail-client/lib/drafts.d.ts

@@ -0,0 +1,42 @@
+import type { Email, EmailListItem } from '../../types.js';
+interface Draft {
+    id: string;
+    message: Email;
+}
+interface DraftListItem {
+    id: string;
+    message: EmailListItem;
+}
+/**
+ * Creates a new draft email
+ */
+export declare function createDraft(baseUrl: string, headers: Record<string, string>, from: string, options: {
+    to: string;
+    subject: string;
+    body: string;
+    cc?: string;
+    bcc?: string;
+    threadId?: string;
+    inReplyTo?: string;
+    references?: string;
+}): Promise<Draft>;
+/**
+ * Gets a draft by ID
+ */
+export declare function getDraft(baseUrl: string, headers: Record<string, string>, draftId: string): Promise<Draft>;
+/**
+ * Lists drafts
+ */
+export declare function listDrafts(baseUrl: string, headers: Record<string, string>, options?: {
+    maxResults?: number;
+    pageToken?: string;
+}): Promise<{
+    drafts: DraftListItem[];
+    nextPageToken?: string;
+    resultSizeEstimate?: number;
+}>;
+/**
+ * Deletes a draft
+ */
+export declare function deleteDraft(baseUrl: string, headers: Record<string, string>, draftId: string): Promise<void>;
+export {};

package/shared/gmail-client/lib/drafts.js

@@ -0,0 +1,81 @@
+import { handleApiError } from './api-errors.js';
+import { buildMimeMessage, toBase64Url } from './mime-utils.js';
+/**
+ * Creates a new draft email
+ */
+export async function createDraft(baseUrl, headers, from, options) {
+    const url = `${baseUrl}/drafts`;
+    const rawMessage = buildMimeMessage(from, options);
+    const encodedMessage = toBase64Url(rawMessage);
+    const requestBody = {
+        message: {
+            raw: encodedMessage,
+        },
+    };
+    if (options.threadId) {
+        requestBody.message.threadId = options.threadId;
+    }
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify(requestBody),
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'creating draft');
+    }
+    return (await response.json());
+}
+/**
+ * Gets a draft by ID
+ */
+export async function getDraft(baseUrl, headers, draftId) {
+    const url = `${baseUrl}/drafts/${draftId}`;
+    const response = await fetch(url, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'getting draft', draftId);
+    }
+    return (await response.json());
+}
+/**
+ * Lists drafts
+ */
+export async function listDrafts(baseUrl, headers, options) {
+    const params = new URLSearchParams();
+    if (options?.maxResults) {
+        params.set('maxResults', options.maxResults.toString());
+    }
+    if (options?.pageToken) {
+        params.set('pageToken', options.pageToken);
+    }
+    const queryString = params.toString();
+    const url = `${baseUrl}/drafts${queryString ? `?${queryString}` : ''}`;
+    const response = await fetch(url, {
+        method: 'GET',
+        headers,
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'listing drafts');
+    }
+    const data = (await response.json());
+    return {
+        drafts: data.drafts ?? [],
+        nextPageToken: data.nextPageToken,
+        resultSizeEstimate: data.resultSizeEstimate,
+    };
+}
+/**
+ * Deletes a draft
+ */
+export async function deleteDraft(baseUrl, headers, draftId) {
+    const url = `${baseUrl}/drafts/${draftId}`;
+    const response = await fetch(url, {
+        method: 'DELETE',
+        headers,
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'deleting draft', draftId);
+    }
+}

package/shared/gmail-client/lib/mime-utils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * MIME message utilities for building and encoding email messages
+ */
+export interface MimeMessageOptions {
+    to: string;
+    subject: string;
+    body: string;
+    cc?: string;
+    bcc?: string;
+    inReplyTo?: string;
+    references?: string;
+}
+/**
+ * Builds a MIME message from email options
+ */
+export declare function buildMimeMessage(from: string, options: MimeMessageOptions): string;
+/**
+ * Converts a string to base64url encoding (RFC 4648)
+ */
+export declare function toBase64Url(str: string): string;

package/shared/gmail-client/lib/mime-utils.js

@@ -0,0 +1,38 @@
+/**
+ * MIME message utilities for building and encoding email messages
+ */
+/**
+ * Builds a MIME message from email options
+ */
+export function buildMimeMessage(from, options) {
+    const headers = [
+        `From: ${from}`,
+        `To: ${options.to}`,
+        `Subject: ${options.subject}`,
+        'MIME-Version: 1.0',
+        'Content-Type: text/plain; charset=utf-8',
+    ];
+    if (options.cc) {
+        headers.push(`Cc: ${options.cc}`);
+    }
+    if (options.bcc) {
+        headers.push(`Bcc: ${options.bcc}`);
+    }
+    if (options.inReplyTo) {
+        headers.push(`In-Reply-To: ${options.inReplyTo}`);
+    }
+    if (options.references) {
+        headers.push(`References: ${options.references}`);
+    }
+    return headers.join('\r\n') + '\r\n\r\n' + options.body;
+}
+/**
+ * Converts a string to base64url encoding (RFC 4648)
+ */
+export function toBase64Url(str) {
+    return Buffer.from(str, 'utf-8')
+        .toString('base64')
+        .replace(/\+/g, '-')
+        .replace(/\//g, '_')
+        .replace(/=+$/, '');
+}

package/shared/gmail-client/lib/modify-message.d.ts

@@ -0,0 +1,9 @@
+import type { Email } from '../../types.js';
+/**
+ * Modifies labels on a message
+ * Used for marking read/unread, starring, archiving, etc.
+ */
+export declare function modifyMessage(baseUrl: string, headers: Record<string, string>, messageId: string, options: {
+    addLabelIds?: string[];
+    removeLabelIds?: string[];
+}): Promise<Email>;

package/shared/gmail-client/lib/modify-message.js

@@ -0,0 +1,20 @@
+import { handleApiError } from './api-errors.js';
+/**
+ * Modifies labels on a message
+ * Used for marking read/unread, starring, archiving, etc.
+ */
+export async function modifyMessage(baseUrl, headers, messageId, options) {
+    const url = `${baseUrl}/messages/${messageId}/modify`;
+    const response = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: JSON.stringify({
+            addLabelIds: options.addLabelIds || [],
+            removeLabelIds: options.removeLabelIds || [],
+        }),
+    });
+    if (!response.ok) {
+        handleApiError(response.status, 'modifying message', messageId);
+    }
+    return (await response.json());
+}