Google Workspace MCP Server

Initiates the Google OAuth 2.0 authentication flow for the specified user email and service. This is the primary method to establish credentials when no valid session exists or when targeting a specific account for a particular service. It generates an authorization URL that the LLM must present to the user. The authentication attempt is linked to the current MCP session via `mcp_session_id`. LLM Guidance: - Use this tool when you need to authenticate a user for a specific Google service (e.g., "Google Calendar", "Google Docs", "Gmail", "Google Drive") and don't have existing valid credentials for the session or specified email. - You MUST provide the `user_google_email` and the `service_name`. If you don't know the email, ask the user first. - Valid `service_name` values typically include "Google Calendar", "Google Docs", "Gmail", "Google Drive". - After calling this tool, present the returned authorization URL clearly to the user and instruct them to: 1. Click the link and complete the sign-in/consent process in their browser. 2. Note the authenticated email displayed on the success page. 3. Provide that email back to you (the LLM). 4. Retry their original request, including the confirmed `user_google_email`. Args: user_google_email (str): The user's full Google email address (e.g., 'example@gmail.com'). This is REQUIRED. service_name (str): The name of the Google service for which authentication is being requested (e.g., "Google Calendar", "Google Docs"). This is REQUIRED. mcp_session_id (Optional[str]): The active MCP session ID (automatically injected by FastMCP from the Mcp-Session-Id header). Links the OAuth flow state to the session. Returns: str: A detailed message for the LLM with the authorization URL and instructions to guide the user through the authentication process.

Searches messages in a user's Gmail account based on a query. Returns both Message IDs and Thread IDs for each found message, along with Gmail web interface links for manual verification. Args: query (str): The search query. Supports standard Gmail search operators. user_google_email (str): The user's Google email address. Required. page_size (int): The maximum number of messages to return. Defaults to 10. Returns: str: LLM-friendly structured results with Message IDs, Thread IDs, and clickable Gmail web interface URLs for each found message.

Retrieves the full content (subject, sender, plain text body) of a specific Gmail message. Args: message_id (str): The unique ID of the Gmail message to retrieve. user_google_email (str): The user's Google email address. Required. Returns: str: The message details including subject, sender, and body content.

Retrieves the content of multiple Gmail messages in a single batch request. Supports up to 100 messages per request using Google's batch API. Args: message_ids (List[str]): List of Gmail message IDs to retrieve (max 100). user_google_email (str): The user's Google email address. Required. format (Literal["full", "metadata"]): Message format. "full" includes body, "metadata" only headers. Returns: str: A formatted list of message contents with separators.

Sends an email using the user's Gmail account. Args: to (str): Recipient email address. subject (str): Email subject. body (str): Email body (plain text). user_google_email (str): The user's Google email address. Required. Returns: str: Confirmation message with the sent email's message ID.

Creates a draft email in the user's Gmail account. Args: user_google_email (str): The user's Google email address. Required. subject (str): Email subject. body (str): Email body (plain text). to (Optional[str]): Optional recipient email address. Can be left empty for drafts. Returns: str: Confirmation message with the created draft's ID.

Retrieves the complete content of a Gmail conversation thread, including all messages. Args: thread_id (str): The unique ID of the Gmail thread to retrieve. user_google_email (str): The user's Google email address. Required. Returns: str: The complete thread content with all messages formatted for reading.

Lists all labels in the user's Gmail account. Args: user_google_email (str): The user's Google email address. Required. Returns: str: A formatted list of all labels with their IDs, names, and types.

Manages Gmail labels: create, update, or delete labels. Args: user_google_email (str): The user's Google email address. Required. action (Literal["create", "update", "delete"]): Action to perform on the label. name (Optional[str]): Label name. Required for create, optional for update. label_id (Optional[str]): Label ID. Required for update and delete operations. label_list_visibility (Literal["labelShow", "labelHide"]): Whether the label is shown in the label list. message_list_visibility (Literal["show", "hide"]): Whether the label is shown in the message list. Returns: str: Confirmation message of the label operation.

Adds or removes labels from a Gmail message. Args: user_google_email (str): The user's Google email address. Required. message_id (str): The ID of the message to modify. add_label_ids (Optional[List[str]]): List of label IDs to add to the message. remove_label_ids (Optional[List[str]]): List of label IDs to remove from the message. Returns: str: Confirmation message of the label changes applied to the message.

Searches for files and folders within a user's Google Drive, including shared drives. Args: user_google_email (str): The user's Google email address. Required. query (str): The search query string. Supports Google Drive search operators. page_size (int): The maximum number of files to return. Defaults to 10. drive_id (Optional[str]): ID of the shared drive to search. If None, behavior depends on `corpora` and `include_items_from_all_drives`. include_items_from_all_drives (bool): Whether shared drive items should be included in results. Defaults to True. This is effective when not specifying a `drive_id`. corpora (Optional[str]): Bodies of items to query (e.g., 'user', 'domain', 'drive', 'allDrives'). If 'drive_id' is specified and 'corpora' is None, it defaults to 'drive'. Otherwise, Drive API default behavior applies. Prefer 'user' or 'drive' over 'allDrives' for efficiency. Returns: str: A formatted list of found files/folders with their details (ID, name, type, size, modified time, link).

Retrieves the content of a specific Google Drive file by ID, supporting files in shared drives. • Native Google Docs, Sheets, Slides → exported as text / CSV. • Office files (.docx, .xlsx, .pptx) → unzipped & parsed with std-lib to extract readable text. • Any other file → downloaded; tries UTF-8 decode, else notes binary. Args: user_google_email: The user’s Google email address. file_id: Drive file ID. Returns: str: The file content as plain text with metadata header.

Retrieves a list of calendars accessible to the authenticated user. Args: user_google_email (str): The user's Google email address. Required. Returns: str: A formatted list of the user's calendars (summary, ID, primary status).

Retrieves a list of events from a specified Google Calendar within a given time range. Args: user_google_email (str): The user's Google email address. Required. calendar_id (str): The ID of the calendar to query. Use 'primary' for the user's primary calendar. Defaults to 'primary'. Calendar IDs can be obtained using `list_calendars`. time_min (Optional[str]): The start of the time range (inclusive) in RFC3339 format (e.g., '2024-05-12T10:00:00Z' or '2024-05-12'). If omitted, defaults to the current time. time_max (Optional[str]): The end of the time range (exclusive) in RFC3339 format. If omitted, events starting from `time_min` onwards are considered (up to `max_results`). max_results (int): The maximum number of events to return. Defaults to 25. Returns: str: A formatted list of events (summary, start time, link) within the specified range.

Creates a new event. Args: user_google_email (str): The user's Google email address. Required. summary (str): Event title. start_time (str): Start time (RFC3339, e.g., "2023-10-27T10:00:00-07:00" or "2023-10-27" for all-day). end_time (str): End time (RFC3339, e.g., "2023-10-27T11:00:00-07:00" or "2023-10-28" for all-day). calendar_id (str): Calendar ID (default: 'primary'). description (Optional[str]): Event description. location (Optional[str]): Event location. attendees (Optional[List[str]]): Attendee email addresses. timezone (Optional[str]): Timezone (e.g., "America/New_York"). Returns: str: Confirmation message of the successful event creation with event link.

Modifies an existing event. Args: user_google_email (str): The user's Google email address. Required. event_id (str): The ID of the event to modify. calendar_id (str): Calendar ID (default: 'primary'). summary (Optional[str]): New event title. start_time (Optional[str]): New start time (RFC3339, e.g., "2023-10-27T10:00:00-07:00" or "2023-10-27" for all-day). end_time (Optional[str]): New end time (RFC3339, e.g., "2023-10-27T11:00:00-07:00" or "2023-10-28" for all-day). description (Optional[str]): New event description. location (Optional[str]): New event location. attendees (Optional[List[str]]): New attendee email addresses. timezone (Optional[str]): New timezone (e.g., "America/New_York"). Returns: str: Confirmation message of the successful event modification with event link.

Deletes an existing event. Args: user_google_email (str): The user's Google email address. Required. event_id (str): The ID of the event to delete. calendar_id (str): Calendar ID (default: 'primary'). Returns: str: Confirmation message of the successful event deletion.

Searches for Google Docs by name using Drive API (mimeType filter). Returns: str: A formatted list of Google Docs matching the search query.

Retrieves content of a Google Doc or a Drive file (like .docx) identified by document_id. - Native Google Docs: Fetches content via Docs API. - Office files (.docx, etc.) stored in Drive: Downloads via Drive API and extracts text. Returns: str: The document content with metadata header.

Lists Google Docs within a specific Drive folder. Returns: str: A formatted list of Google Docs in the specified folder.

Creates a new Google Doc and optionally inserts initial content. Returns: str: Confirmation message with document ID and link.

Lists spreadsheets from Google Drive that the user has access to. Args: user_google_email (str): The user's Google email address. Required. max_results (int): Maximum number of spreadsheets to return. Defaults to 25. Returns: str: A formatted list of spreadsheet files (name, ID, modified time).

Gets information about a specific spreadsheet including its sheets. Args: user_google_email (str): The user's Google email address. Required. spreadsheet_id (str): The ID of the spreadsheet to get info for. Required. Returns: str: Formatted spreadsheet information including title and sheets list.

Reads values from a specific range in a Google Sheet. Args: user_google_email (str): The user's Google email address. Required. spreadsheet_id (str): The ID of the spreadsheet. Required. range_name (str): The range to read (e.g., "Sheet1!A1:D10", "A1:D10"). Defaults to "A1:Z1000". Returns: str: The formatted values from the specified range.

Modifies values in a specific range of a Google Sheet - can write, update, or clear values. Args: user_google_email (str): The user's Google email address. Required. spreadsheet_id (str): The ID of the spreadsheet. Required. range_name (str): The range to modify (e.g., "Sheet1!A1:D10", "A1:D10"). Required. values (Optional[List[List[str]]]): 2D array of values to write/update. Required unless clear_values=True. value_input_option (str): How to interpret input values ("RAW" or "USER_ENTERED"). Defaults to "USER_ENTERED". clear_values (bool): If True, clears the range instead of writing values. Defaults to False. Returns: str: Confirmation message of the successful modification operation.

Creates a new Google Spreadsheet. Args: user_google_email (str): The user's Google email address. Required. title (str): The title of the new spreadsheet. Required. sheet_names (Optional[List[str]]): List of sheet names to create. If not provided, creates one sheet with default name. Returns: str: Information about the newly created spreadsheet including ID and URL.

Creates a new sheet within an existing spreadsheet. Args: user_google_email (str): The user's Google email address. Required. spreadsheet_id (str): The ID of the spreadsheet. Required. sheet_name (str): The name of the new sheet. Required. Returns: str: Confirmation message of the successful sheet creation.

Lists Google Chat spaces (rooms and direct messages) accessible to the user. Returns: str: A formatted list of Google Chat spaces accessible to the user.

Retrieves messages from a Google Chat space. Returns: str: Formatted messages from the specified space.

Sends a message to a Google Chat space. Returns: str: Confirmation message with sent message details.

Searches for messages in Google Chat spaces by text content. Returns: str: A formatted list of messages matching the search query.

Create a new form using the title given in the provided form message in the request. Args: user_google_email (str): The user's Google email address. Required. title (str): The title of the form. description (Optional[str]): The description of the form. document_title (Optional[str]): The document title (shown in browser tab). Returns: str: Confirmation message with form ID and edit URL.

Get a form. Args: user_google_email (str): The user's Google email address. Required. form_id (str): The ID of the form to retrieve. Returns: str: Form details including title, description, questions, and URLs.

Updates the publish settings of a form. Args: user_google_email (str): The user's Google email address. Required. form_id (str): The ID of the form to update publish settings for. publish_as_template (bool): Whether to publish as a template. Defaults to False. require_authentication (bool): Whether to require authentication to view/submit. Defaults to False. Returns: str: Confirmation message of the successful publish settings update.

Get one response from the form. Args: user_google_email (str): The user's Google email address. Required. form_id (str): The ID of the form. response_id (str): The ID of the response to retrieve. Returns: str: Response details including answers and metadata.

List a form's responses. Args: user_google_email (str): The user's Google email address. Required. form_id (str): The ID of the form. page_size (int): Maximum number of responses to return. Defaults to 10. page_token (Optional[str]): Token for retrieving next page of results. Returns: str: List of responses with basic details and pagination info.