Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/server.py:499-508 (handler)

  Primary handler logic for the 'gmail_list_unread' tool. Parses input arguments, constructs a SearchQuery object with is_unread=True and optional category filter, invokes GmailClient.list_emails, formats the results using _format_email_list, and returns as TextContent.

  elif name == "gmail_list_unread":
      category = arguments.get("category")
      max_results = arguments.get("max_results", 20)
      search = SearchQuery(
          is_unread=True,
          category=category,
          max_results=max_results,
      )
      results = await client.list_emails(search)
      return [TextContent(type="text", text=_format_email_list(results))]

• src/mcp_gmail/server.py:76-93 (schema)

  JSON schema definition for the 'gmail_list_unread' tool inputs: optional 'category' (string enum) and 'max_results' (integer). Defines the tool interface for MCP clients.

  Tool(
      name="gmail_list_unread",
      description="List unread emails from the inbox. Optionally filter by a pre-configured category such as navy, kids, financial, or action_required.",
      inputSchema={
          "type": "object",
          "properties": {
              "category": {
                  "type": "string",
                  "description": "Filter by category name. Must be one of: navy, kids, financial, action_required. Leave empty for all unread emails."
              },
              "max_results": {
                  "type": "integer",
                  "description": "Maximum number of emails to return. Default is 20."
              }
          },
          "required": []
      },
  ),

• src/mcp_gmail/server.py:1128-1131 (registration)

  Registers all tools including 'gmail_list_unread' by returning the predefined GMAIL_TOOLS list from the list_tools handler decorated with @server.list_tools().

  @server.list_tools()
  async def list_tools() -> list[Tool]:
      return GMAIL_TOOLS

• src/mcp_gmail/gmail_client.py:278-317 (helper)

  Core helper method implementing the email listing logic. Builds Gmail API search query (adds 'is:unread' if specified), fetches messages, parses into EmailSummary, applies category filtering post-fetch, handles API errors.

  async def list_emails(self, search: SearchQuery) -> list[EmailSummary]:
      """List emails matching search criteria."""
      query = self._build_query(search)
      logger.info(f"Searching emails with query: {query}")
  
      try:
          results = (
              self.service.users()
              .messages()
              .list(userId="me", q=query, maxResults=search.max_results)
              .execute()
          )
  
          messages = results.get("messages", [])
          if not messages:
              return []
  
          # Fetch each message's metadata
          summaries = []
          for msg_ref in messages:
              msg = (
                  self.service.users()
                  .messages()
                  .get(userId="me", id=msg_ref["id"], format="metadata")
                  .execute()
              )
              email = self._parse_message(msg)
  
              # Filter by category if specified
              if search.category:
                  if search.category not in email.categories:
                      continue
  
              summaries.append(self._email_to_summary(email))
  
          return summaries
      except HttpError as e:
          logger.error(f"Failed to list emails: {e}")
          raise

• src/mcp_gmail/models.py:98-111 (schema)

  Pydantic model defining the SearchQuery used by the tool, including fields like category, is_unread, and max_results for structured query building and validation.

  class SearchQuery(BaseModel):
      """Search query parameters."""
  
      query: Optional[str] = Field(default=None, description="Gmail search query")
      sender: Optional[str] = Field(default=None, description="Filter by sender")
      subject: Optional[str] = Field(default=None, description="Filter by subject")
      labels: list[str] = Field(default_factory=list, description="Filter by labels")
      category: Optional[str] = Field(default=None, description="Filter by our category")
      is_unread: Optional[bool] = Field(default=None, description="Filter by read status")
      has_attachment: Optional[bool] = Field(default=None)
      after_date: Optional[datetime] = Field(default=None)
      before_date: Optional[datetime] = Field(default=None)
      max_results: int = Field(default=20, ge=1, le=100)