Google Workspace

Google Workspace MCP Skill

Interact with Gmail, Google Calendar, and Google Contacts through the google-workspace MCP server.

Quick Start

1. Discover available tools:

ls .kodelet/mcp/servers/google-workspace/

2. Read function signatures before use:

file_read .kodelet/mcp/servers/google-workspace/gmailSearchEmails.ts

3. Write TypeScript to .kodelet/mcp/ and execute via code_execution.

Common Workflows

List Accounts (Always First)

import * as gmail from './servers/google-workspace/index.js';

const { accounts } = await gmail.gmailListAccounts({});
const account = accounts[0];

Search Emails

const results = await gmail.gmailSearchEmails({
  query: 'from:billing@example.com after:2025/01/01 has:attachment',
  account: account,
  max_results: 50
});

for (const email of results.emails) {
  console.log(`${email.date} | ${email.from} | ${email.subject}`);
}

Download Attachments

import * as fs from 'fs';

for (const email of results.emails) {
  if (email.attachments) {
    for (const att of email.attachments) {
      const data = await gmail.gmailGetAttachment({
        account: account,
        message_id: email.id,
        attachment_id: att.id
      });
      const buffer = Buffer.from(data.data_base64, 'base64');
      fs.writeFileSync(`/tmp/${att.filename}`, buffer);
    }
  }
}

Send Email

await gmail.gmailSendEmail({
  account: account,
  to: ['recipient@example.com'],
  subject: 'Hello',
  body: 'Plain text body',
  html_body: '<p>HTML body</p>'  // optional
});

Search Contacts

const contacts = await gmail.gmailSearchContacts({
  account: account,
  query: 'John'
});

Create All-Day Event (OOO, Holiday Block)

import * as gw from './servers/google-workspace/index.js';

const { accounts } = await gw.gmailListAccounts({});
const account = accounts[0];

// end_date is EXCLUSIVE - '2026-01-05' means event covers through Jan 4
const result = await gw.calendarCreateEvent({
  account: account,
  summary: '🎄 OOO - Christmas Holiday',
  description: 'Out of office for holiday.',
  start_date: '2025-12-22',      // YYYY-MM-DD format
  end_date: '2026-01-05',        // Exclusive - event ends Jan 4
  visibility: 'public',
  use_default_reminders: false   // Recommended for OOO blocks
});

Create Timed Event with Google Meet

const result = await gw.calendarCreateEvent({
  account: account,
  summary: 'Meeting: Project Discussion',
  description: 'Agenda: Review project status',
  attendees: ['attendee@example.com'],
  start_date_time: '2026-01-06T20:00:00',  // RFC3339 format
  end_date_time: '2026-01-06T21:00:00',
  time_zone: 'Europe/London',
  add_conferencing: true,        // Adds Google Meet
  use_default_reminders: true
});

// Get Google Meet link from response
if (result.conference_data?.entry_points) {
  const meetLink = result.conference_data.entry_points.find(e => e.entry_point_type === 'video');
  console.log(`Google Meet: ${meetLink?.uri}`);
}

Update Event Attendees

await gw.calendarUpdateEvent({
  account: account,
  event_id: 'event_id_here',
  attendees: ['corrected.email@example.com']
});

Delete and Recreate Event (Workaround for Reminder Bugs)

When updating events, you may encounter "Cannot specify both default reminders and overrides" error. The workaround is to delete and recreate:

await gw.calendarDeleteEvent({
  account: account,
  event_id: 'old_event_id'
});

const result = await gw.calendarCreateEvent({
  account: account,
  // ... new event properties
  use_default_reminders: false  // Explicitly set to avoid conflicts
});

Gmail Search Query Syntax

Combine operators: from:boss@company.com is:unread has:attachment

Available Tools

Email Operations (Gmail)

• gmailListAccounts - List connected accounts (call first!)
• gmailListEmails - List emails with query/labels
• gmailGetEmail - Get email by ID
• gmailSearchEmails - Search emails
• gmailSendEmail - Send email (HTML, CC, BCC, attachments)

Email Actions

• gmailMarkRead / gmailMarkUnread
• gmailStarEmail / gmailUnstarEmail
• gmailArchiveEmail - Remove from inbox
• gmailTrashEmail / gmailDeleteEmail
• gmailModifyLabels - Add/remove labels

Labels

• gmailListLabels / gmailCreateLabel / gmailUpdateLabel / gmailDeleteLabel

Attachments

• gmailGetAttachment - Returns base64 data

Filters

• gmailListFilters / gmailCreateFilter / gmailDeleteFilter

Contacts

• gmailListContacts / gmailSearchContacts
• gmailCreateContact / gmailUpdateContact / gmailDeleteContact

Calendar Events

• calendarListEvents / calendarSearchEvents / calendarGetEvent
• calendarCreateEvent - Create with attendees, Google Meet, reminders
• calendarUpdateEvent - Modify existing event
• calendarDeleteEvent / calendarDeleteFutureEvents
• calendarQuickAddEvent - Create from natural language string
• calendarGetRecurringInstances - Get instances of recurring event

Calendar Management

• calendarListCalendars / calendarCreateCalendar / calendarUpdateCalendar / calendarDeleteCalendar
• calendarAddConferencing - Add Google Meet to existing event
• calendarUpdateReminders - Modify event reminders
• calendarMoveEvent - Move to different calendar
• calendarRespondToEvent - Accept/decline/tentative
• calendarFindAvailableSlots / calendarGetFreeBusy - Check availability

Key Calendar Notes

Processing Downloaded Attachments

After downloading attachments, use appropriate skills:

• PDF files: Use pdf skill for text/table extraction
• XLSX files: Use xlsx skill for spreadsheet analysis
• DOCX files: Use docx skill for document processing

Converted and distributed by TomeVault — claim your Tome and manage your conversions.