Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/gmail_client.py:817-917 (handler)

  Core implementation of the gmail_send_email tool in GmailClient class. Constructs MIME message, handles reply-to threading by fetching original message headers, base64 encodes, and sends via Gmail API users.messages.send.

  async def send_email(
      self,
      to: list[str],
      subject: str,
      body: str,
      cc: list[str] | None = None,
      bcc: list[str] | None = None,
      reply_to_message_id: str | None = None,
  ) -> dict:
      """Send an email.
      
      Args:
          to: List of recipient email addresses
          subject: Email subject
          body: Email body (plain text)
          cc: Optional CC recipients
          bcc: Optional BCC recipients
          reply_to_message_id: Optional message ID to reply to (for threading)
          
      Returns:
          Dict with sent message info or error
      """
      try:
          # Create the email message
          message = MIMEText(body)
          message['to'] = ', '.join(to)
          message['subject'] = subject
          
          if cc:
              message['cc'] = ', '.join(cc)
          if bcc:
              message['bcc'] = ', '.join(bcc)
          
          # Handle reply threading
          thread_id = None
          if reply_to_message_id:
              # Get the original message to get thread ID and references
              try:
                  original = self.service.users().messages().get(
                      userId="me", 
                      id=reply_to_message_id,
                      format="metadata",
                      metadataHeaders=["Message-ID", "References", "In-Reply-To"]
                  ).execute()
                  
                  thread_id = original.get("threadId")
                  
                  # Get original Message-ID for threading headers
                  headers = original.get("payload", {}).get("headers", [])
                  original_message_id = None
                  references = None
                  
                  for header in headers:
                      if header["name"].lower() == "message-id":
                          original_message_id = header["value"]
                      elif header["name"].lower() == "references":
                          references = header["value"]
                  
                  # Set threading headers
                  if original_message_id:
                      message['In-Reply-To'] = original_message_id
                      if references:
                          message['References'] = f"{references} {original_message_id}"
                      else:
                          message['References'] = original_message_id
                          
              except HttpError as e:
                  logger.warning(f"Could not get original message for threading: {e}")
          
          # Encode the message
          raw_message = base64.urlsafe_b64encode(message.as_bytes()).decode('utf-8')
          
          # Send the message
          body_data = {'raw': raw_message}
          if thread_id:
              body_data['threadId'] = thread_id
              
          sent_message = self.service.users().messages().send(
              userId="me",
              body=body_data
          ).execute()
          
          logger.info(f"Email sent successfully. Message ID: {sent_message['id']}")
          
          return {
              "success": True,
              "message_id": sent_message["id"],
              "thread_id": sent_message.get("threadId"),
              "to": to,
              "subject": subject,
          }
          
      except HttpError as e:
          logger.error(f"Failed to send email: {e}")
          return {
              "success": False,
              "error": str(e),
              "to": to,
              "subject": subject,
          }

• src/mcp_gmail/server_old.py:448-505 (handler)

  MCP tool dispatcher handler for 'gmail_send_email'. Validates input arguments, provides preview mode if confirm=false, and delegates to GmailClient.send_email when confirmed.

  elif name == "gmail_send_email":
      to = arguments.get("to", [])
      subject = arguments.get("subject", "")
      body = arguments.get("body", "")
      cc = arguments.get("cc", [])
      bcc = arguments.get("bcc", [])
      reply_to_message_id = arguments.get("reply_to_message_id")
      confirm = arguments.get("confirm", False)
      
      # Validate required fields
      if not to:
          return [TextContent(type="text", text="Error: 'to' recipients are required.")]
      if not subject:
          return [TextContent(type="text", text="Error: 'subject' is required.")]
      if not body:
          return [TextContent(type="text", text="Error: 'body' is required.")]
      
      if not confirm:
          # Preview mode
          lines = [
              "⚠️ Preview: The following email would be sent:\n",
              f"To: {', '.join(to)}",
          ]
          if cc:
              lines.append(f"CC: {', '.join(cc)}")
          if bcc:
              lines.append(f"BCC: {', '.join(bcc)}")
          lines.append(f"Subject: {subject}")
          if reply_to_message_id:
              lines.append(f"Reply to message: {reply_to_message_id}")
          lines.append(f"\n--- Body ---\n{body[:500]}")
          if len(body) > 500:
              lines.append(f"\n... ({len(body) - 500} more characters)")
          lines.append("\n\nTo send this email, call this tool again with confirm=true")
          
          return [TextContent(type="text", text="\n".join(lines))]
      else:
          # Actually send the email
          result = await client.send_email(
              to=to,
              subject=subject,
              body=body,
              cc=cc if cc else None,
              bcc=bcc if bcc else None,
              reply_to_message_id=reply_to_message_id,
          )
          
          if result["success"]:
              return [TextContent(
                  type="text",
                  text=f"✅ Email sent successfully!\n\nTo: {', '.join(result['to'])}\nSubject: {result['subject']}\nMessage ID: {result['message_id']}"
              )]
          else:
              return [TextContent(
                  type="text",
                  text=f"❌ Failed to send email.\n\nError: {result['error']}"
              )]

• src/mcp_gmail/server_old.py:189-230 (registration)

  Tool registration in list_tools() decorator, including name, description, and full inputSchema for parameter validation.

  Tool(
      name="gmail_send_email",
      description="Send an email. Can send new emails or reply to existing threads.",
      inputSchema={
          "type": "object",
          "properties": {
              "to": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "List of recipient email addresses",
              },
              "subject": {
                  "type": "string",
                  "description": "Email subject line",
              },
              "body": {
                  "type": "string",
                  "description": "Email body text (plain text)",
              },
              "cc": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "CC recipients (optional)",
              },
              "bcc": {
                  "type": "array",
                  "items": {"type": "string"},
                  "description": "BCC recipients (optional)",
              },
              "reply_to_message_id": {
                  "type": "string",
                  "description": "Message ID to reply to (optional, for threading)",
              },
              "confirm": {
                  "type": "boolean",
                  "description": "Must be true to actually send the email. Set to false to preview.",
                  "default": False,
              },
          },
          "required": ["to", "subject", "body"],
      },
  ),

• src/mcp_gmail/server_old.py:192-229 (schema)

  JSON schema definition for gmail_send_email tool inputs, defining properties, descriptions, defaults, and required fields.

  inputSchema={
      "type": "object",
      "properties": {
          "to": {
              "type": "array",
              "items": {"type": "string"},
              "description": "List of recipient email addresses",
          },
          "subject": {
              "type": "string",
              "description": "Email subject line",
          },
          "body": {
              "type": "string",
              "description": "Email body text (plain text)",
          },
          "cc": {
              "type": "array",
              "items": {"type": "string"},
              "description": "CC recipients (optional)",
          },
          "bcc": {
              "type": "array",
              "items": {"type": "string"},
              "description": "BCC recipients (optional)",
          },
          "reply_to_message_id": {
              "type": "string",
              "description": "Message ID to reply to (optional, for threading)",
          },
          "confirm": {
              "type": "boolean",
              "description": "Must be true to actually send the email. Set to false to preview.",
              "default": False,
          },
      },
      "required": ["to", "subject", "body"],
  },