Google Workspace MCP Server - Control Gmail, Calendar, Docs, Sheets, Slides, Chat, Forms & Drive

Instructions

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.

Implementation Reference

• gmail/gmail_tools.py:707-804 (handler)

  The primary handler for the 'send_gmail_message' MCP tool. Decorated with @server.tool() for registration. Uses Gmail API to send emails, supports threading/replies, plain/HTML body, CC/BCC. Relies on helper _prepare_gmail_message for MIME message construction.

  @server.tool()
  @handle_http_errors("send_gmail_message", service_type="gmail")
  @require_google_service("gmail", GMAIL_SEND_SCOPE)
  async def send_gmail_message(
      service,
      user_google_email: str,
      to: str = Body(..., description="Recipient email address."),
      subject: str = Body(..., description="Email subject."),
      body: str = Body(..., description="Email body content (plain text or HTML)."),
      body_format: Literal["plain", "html"] = Body(
          "plain", description="Email body format. Use 'plain' for plaintext or 'html' for HTML content."
      ),
      cc: Optional[str] = Body(None, description="Optional CC email address."),
      bcc: Optional[str] = Body(None, description="Optional BCC email address."),
      thread_id: Optional[str] = Body(None, description="Optional Gmail thread ID to reply within."),
      in_reply_to: Optional[str] = Body(None, description="Optional Message-ID of the message being replied to."),
      references: Optional[str] = Body(None, description="Optional chain of Message-IDs for proper threading."),
  ) -> str:
      """
      Sends an email using the user's Gmail account. Supports both new emails and replies.
  
      Args:
          to (str): Recipient email address.
          subject (str): Email subject.
          body (str): Email body content.
          body_format (Literal['plain', 'html']): Email body format. Defaults to 'plain'.
          cc (Optional[str]): Optional CC email address.
          bcc (Optional[str]): Optional BCC email address.
          user_google_email (str): The user's Google email address. Required.
          thread_id (Optional[str]): Optional Gmail thread ID to reply within. When provided, sends a reply.
          in_reply_to (Optional[str]): Optional Message-ID of the message being replied to. Used for proper threading.
          references (Optional[str]): Optional chain of Message-IDs for proper threading. Should include all previous Message-IDs.
  
      Returns:
          str: Confirmation message with the sent email's message ID.
  
      Examples:
          # Send a new email
          send_gmail_message(to="user@example.com", subject="Hello", body="Hi there!")
  
          # Send an HTML email
          send_gmail_message(
              to="user@example.com",
              subject="Hello",
              body="<strong>Hi there!</strong>",
              body_format="html"
          )
  
          # Send an email with CC and BCC
          send_gmail_message(
              to="user@example.com",
              cc="manager@example.com",
              bcc="archive@example.com",
              subject="Project Update",
              body="Here's the latest update..."
          )
  
          # Send a reply
          send_gmail_message(
              to="user@example.com",
              subject="Re: Meeting tomorrow",
              body="Thanks for the update!",
              thread_id="thread_123",
              in_reply_to="<message123@gmail.com>",
              references="<original@gmail.com> <message123@gmail.com>"
          )
      """
      logger.info(
          f"[send_gmail_message] Invoked. Email: '{user_google_email}', Subject: '{subject}'"
      )
  
      # Prepare the email message
      raw_message, thread_id_final = _prepare_gmail_message(
          subject=subject,
          body=body,
          to=to,
          cc=cc,
          bcc=bcc,
          thread_id=thread_id,
          in_reply_to=in_reply_to,
          references=references,
          body_format=body_format,
          from_email=user_google_email,
      )
  
      send_body = {"raw": raw_message}
  
      # Associate with thread if provided
      if thread_id_final:
          send_body["threadId"] = thread_id_final
  
      # Send the message
      sent_message = await asyncio.to_thread(
          service.users().messages().send(userId="me", body=send_body).execute
      )
      message_id = sent_message.get("id")
      return f"Email sent! Message ID: {message_id}"

• gmail/gmail_tools.py:175-241 (helper)

  Helper function used by send_gmail_message to construct the MIME email message, handle threading headers (In-Reply-To, References), support plain/HTML body, and base64 encode the raw message for Gmail API.

  def _prepare_gmail_message(
      subject: str,
      body: str,
      to: Optional[str] = None,
      cc: Optional[str] = None,
      bcc: Optional[str] = None,
      thread_id: Optional[str] = None,
      in_reply_to: Optional[str] = None,
      references: Optional[str] = None,
      body_format: Literal["plain", "html"] = "plain",
      from_email: Optional[str] = None,
  ) -> tuple[str, Optional[str]]:
      """
      Prepare a Gmail message with threading support.
  
      Args:
          subject: Email subject
          body: Email body content
          to: Optional recipient email address
          cc: Optional CC email address
          bcc: Optional BCC email address
          thread_id: Optional Gmail thread ID to reply within
          in_reply_to: Optional Message-ID of the message being replied to
          references: Optional chain of Message-IDs for proper threading
          body_format: Content type for the email body ('plain' or 'html')
          from_email: Optional sender email address
  
      Returns:
          Tuple of (raw_message, thread_id) where raw_message is base64 encoded
      """
      # Handle reply subject formatting
      reply_subject = subject
      if in_reply_to and not subject.lower().startswith('re:'):
          reply_subject = f"Re: {subject}"
  
      # Prepare the email
      normalized_format = body_format.lower()
      if normalized_format not in {"plain", "html"}:
          raise ValueError("body_format must be either 'plain' or 'html'.")
  
      message = MIMEText(body, normalized_format)
      message["Subject"] = reply_subject
  
      # Add sender if provided
      if from_email:
          message["From"] = from_email
  
      # Add recipients if provided
      if to:
          message["To"] = to
      if cc:
          message["Cc"] = cc
      if bcc:
          message["Bcc"] = bcc
  
      # Add reply headers for threading
      if in_reply_to:
          message["In-Reply-To"] = in_reply_to
  
      if references:
          message["References"] = references
  
      # Encode message
      raw_message = base64.urlsafe_b64encode(message.as_bytes()).decode()
  
      return raw_message, thread_id

• gmail/gmail_tools.py:707-707 (registration)

  Decorators on the handler function that register it as an MCP tool via @server.tool(), handle errors, and require Gmail send scope.

  @server.tool()

• gmail/gmail_tools.py:710-724 (schema)

  Input schema defined via FastAPI Body() parameters with descriptions, type hints (str, Optional[str], Literal), and comprehensive docstring with usage examples serving as schema documentation.

  async def send_gmail_message(
      service,
      user_google_email: str,
      to: str = Body(..., description="Recipient email address."),
      subject: str = Body(..., description="Email subject."),
      body: str = Body(..., description="Email body content (plain text or HTML)."),
      body_format: Literal["plain", "html"] = Body(
          "plain", description="Email body format. Use 'plain' for plaintext or 'html' for HTML content."
      ),
      cc: Optional[str] = Body(None, description="Optional CC email address."),
      bcc: Optional[str] = Body(None, description="Optional BCC email address."),
      thread_id: Optional[str] = Body(None, description="Optional Gmail thread ID to reply within."),
      in_reply_to: Optional[str] = Body(None, description="Optional Message-ID of the message being replied to."),
      references: Optional[str] = Body(None, description="Optional chain of Message-IDs for proper threading."),
  ) -> str: