Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/server.py:873-897 (handler)

  Handler function that processes the 'gmail_mark_as_unread_by_ids' tool call, parses arguments, handles confirmation preview, and delegates to GmailClient.mark_as_unread

  elif name == "gmail_mark_as_unread_by_ids":
      message_ids_str = arguments.get("message_ids", "")
      confirm = arguments.get("confirm", False)
      
      if not message_ids_str:
          return [TextContent(type="text", text="Error: message_ids is required.")]
      
      # Parse comma-separated IDs
      message_ids = [mid.strip() for mid in message_ids_str.split(",") if mid.strip()]
      
      if not message_ids:
          return [TextContent(type="text", text="Error: No valid message IDs provided.")]
      
      if not confirm:
          return [TextContent(
              type="text",
              text=f"Preview: {len(message_ids)} email(s) would be marked as unread. Set confirm=true to proceed."
          )]
      
      result = await client.mark_as_unread(message_ids)
      return [TextContent(
          type="text",
          text=f"Success: Marked {result['success']} email(s) as unread."
          + (f" Errors: {result['errors']}" if result['errors'] else "")
      )]

• src/mcp_gmail/server.py:388-404 (schema)

  Tool schema and registration definition for 'gmail_mark_as_unread_by_ids', including input parameters and descriptions

  Tool(
      name="gmail_mark_as_unread_by_ids",
      description="Mark specific emails as unread using their message IDs. Requires confirmation to execute.",
      inputSchema={
          "type": "object",
          "properties": {
              "message_ids": {
                  "type": "string",
                  "description": "Comma-separated list of Gmail message IDs to mark as unread."
              },
              "confirm": {
                  "type": "boolean",
                  "description": "Must be true to actually mark as unread. Set false to preview."
              }
          },
          "required": ["message_ids", "confirm"]
      },

• src/mcp_gmail/gmail_client.py:727-769 (helper)

  Core helper method in GmailClient that performs the batch modification to add UNREAD label to specified message IDs using Gmail API

  async def mark_as_unread(self, message_ids: list[str]) -> dict:
      """Mark one or more emails as unread by adding the UNREAD label.
      
      Args:
          message_ids: List of Gmail message IDs to mark as unread
          
      Returns:
          Dict with success count and any errors
      """
      if not message_ids:
          return {"success": 0, "errors": [], "message": "No message IDs provided"}
      
      results = {"success": 0, "errors": []}
      
      try:
          # Use batchModify for efficiency (up to 1000 at a time)
          if len(message_ids) <= 1000:
              self.service.users().messages().batchModify(
                  userId="me",
                  body={
                      "ids": message_ids,
                      "addLabelIds": ["UNREAD"]
                  }
              ).execute()
              results["success"] = len(message_ids)
          else:
              # Process in batches of 1000
              for i in range(0, len(message_ids), 1000):
                  batch = message_ids[i:i+1000]
                  self.service.users().messages().batchModify(
                      userId="me",
                      body={
                          "ids": batch,
                          "addLabelIds": ["UNREAD"]
                      }
                  ).execute()
                  results["success"] += len(batch)
                  
      except HttpError as e:
          logger.error(f"Failed to mark emails as unread: {e}")
          results["errors"].append(str(e))
          
      return results