Gmail MCP Server

Instructions

Implementation Reference

• src/mcp_gmail/server.py:810-835 (handler)

  Main MCP tool handler that validates input, handles confirmation/preview mode, parses comma-separated message IDs, and invokes GmailClient.mark_as_read.

  elif name == "gmail_mark_as_read_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 read. Set confirm=true to proceed."
          )]
      
      result = await client.mark_as_read(message_ids)
      return [TextContent(
          type="text",
          text=f"Success: Marked {result['success']} email(s) as read."
          + (f" Errors: {result['errors']}" if result['errors'] else "")
      )]

• src/mcp_gmail/server.py:346-362 (schema)

  Tool schema definition including input JSON schema with required parameters: message_ids (comma-separated string) and confirm (boolean).

      name="gmail_mark_as_read_by_ids",
      description="Mark specific emails as read 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 read."
              },
              "confirm": {
                  "type": "boolean",
                  "description": "Must be true to actually mark as read. Set false to preview."
              }
          },
          "required": ["message_ids", "confirm"]
      },
  ),

• src/mcp_gmail/gmail_client.py:637-680 (helper)

  Core GmailClient method implementing the mark as read functionality using Gmail API batchModify to remove the 'UNREAD' label from messages, with batching for large lists and error handling.

  async def mark_as_read(self, message_ids: list[str]) -> dict:
      """Mark one or more emails as read by removing the UNREAD label.
      
      Args:
          message_ids: List of Gmail message IDs to mark as read
          
      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,
                      "removeLabelIds": ["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,
                          "removeLabelIds": ["UNREAD"]
                      }
                  ).execute()
                  results["success"] += len(batch)
                  
      except HttpError as e:
          logger.error(f"Failed to mark emails as read: {e}")
          results["errors"].append(str(e))
          
      return results

• src/mcp_gmail/server.py:1134-1136 (registration)

  MCP server decorator registering the general call_tool handler which dispatches to specific tool handlers like gmail_mark_as_read_by_ids based on name.

  async def call_tool(name: str, arguments: dict[str, Any]) -> list[TextContent]:
      return await handle_call_tool(name, arguments)

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

  MCP server decorator registering list_tools which returns GMAIL_TOOLS containing the gmail_mark_as_read_by_ids tool schema.

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