Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/server_old.py:87-100 (schema)

  Input schema definition for the 'gmail_get_email' tool, specifying the required 'email_id' parameter.
  Tool( name="gmail_get_email", description="Get the full content of a specific email by its ID", inputSchema={ "type": "object", "properties": { "email_id": { "type": "string", "description": "The Gmail message ID", }, }, "required": ["email_id"], }, ),
• src/mcp_gmail/server_old.py:322-332 (handler)

  The main handler in the MCP server's call_tool function that executes the 'gmail_get_email' tool by retrieving the email via GmailClient and formatting it for response.
  elif name == "gmail_get_email": email_id = arguments.get("email_id") if not email_id: return [TextContent(type="text", text="Error: email_id is required")] email = await client.get_email(email_id) return [ TextContent( type="text", text=_format_full_email(email), ) ]
• src/mcp_gmail/gmail_client.py:264-277 (handler)

  Core implementation in GmailClient that fetches the full email from Gmail API using users.messages.get and parses it into an Email object.
  async def get_email(self, message_id: str) -> Email: """Get a single email by ID with full content.""" try: msg = ( self.service.users() .messages() .get(userId="me", id=message_id, format="full") .execute() ) return self._parse_message(msg, include_body=True) except HttpError as e: logger.error(f"Failed to get email {message_id}: {e}") raise
• src/mcp_gmail/server_old.py:752-777 (helper)

  Helper function used by the handler to format the retrieved email into a readable text response.
  def _format_full_email(email) -> str: """Format full email for display.""" categories = f"Categories: {', '.join(email.categories)}" if email.categories else "" attachments = "" if email.attachments: att_list = ", ".join(a.filename for a in email.attachments) attachments = f"\nAttachments: {att_list}" body = email.body_text or "(No text content)" if len(body) > 2000: body = body[:2000] + "\n\n... [truncated]" return f""" **Subject:** {email.subject} **From:** {email.sender} **To:** {', '.join(str(t) for t in email.to)} **Date:** {email.date.strftime('%Y-%m-%d %H:%M:%S')} **Labels:** {', '.join(email.labels)} {categories} {attachments} --- {body} """
• src/mcp_gmail/gmail_client.py:167-221 (helper)

  Helper function in GmailClient that parses the raw Gmail API message into a structured Email object, including body extraction, categorization, and metadata parsing.
  def _parse_message(self, msg: dict, include_body: bool = False) -> Email: """Parse Gmail API message into Email model.""" payload = msg.get("payload", {}) headers = payload.get("headers", []) # Parse date date_str = self._get_header(headers, "Date") try: date = parsedate_to_datetime(date_str) except Exception: # Fallback to internal date internal_date = int(msg.get("internalDate", 0)) / 1000 date = datetime.fromtimestamp(internal_date, tz=timezone.utc) # Parse labels label_ids = msg.get("labelIds", []) is_read = "UNREAD" not in label_ids is_starred = "STARRED" in label_ids is_important = "IMPORTANT" in label_ids # Extract body if requested text_body, html_body = None, None if include_body: text_body, html_body = self._extract_body(payload) # Extract attachments attachments = self._extract_attachments(payload) email = Email( id=msg["id"], thread_id=msg["threadId"], subject=self._get_header(headers, "Subject") or "(No Subject)", snippet=msg.get("snippet", ""), body_text=text_body, body_html=html_body, sender=self._parse_email_address(self._get_header(headers, "From")), to=self._parse_email_addresses(self._get_header(headers, "To")), cc=self._parse_email_addresses(self._get_header(headers, "Cc")), reply_to=self._parse_email_address(self._get_header(headers, "Reply-To")) if self._get_header(headers, "Reply-To") else None, date=date, labels=label_ids, is_read=is_read, is_starred=is_starred, is_important=is_important, attachments=attachments, has_attachments=len(attachments) > 0, ) # Categorize email.categories = self._categorize_email(email) email.priority = self._get_priority(email.categories) return email