Migadu MCP Server

Instructions

Implementation Reference

• migadu_mcp/tools/mailbox_tools.py:236-254 (handler)

  Main handler for the 'delete_mailbox' tool. Registers the tool with FastMCP and orchestrates bulk deletion by calling the process_delete_mailbox helper.

  @mcp.tool(
      annotations={
          "readOnlyHint": False,
          "destructiveHint": True,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  async def delete_mailbox(
      targets: List[Dict[str, Any]], ctx: Context
  ) -> Dict[str, Any]:
      """Delete mailboxes. DESTRUCTIVE: Cannot be undone. List of dicts with: target (email/local)."""
      count = len(list(ensure_iterable(targets)))
      await log_bulk_operation_start(ctx, "Deleting", count, "mailbox")
      await ctx.warning("🗑️ DESTRUCTIVE: This operation cannot be undone!")
  
      result = await process_delete_mailbox(targets, ctx)
      await log_bulk_operation_result(ctx, "Mailbox deletion", result, "mailbox")
      return result

• migadu_mcp/tools/mailbox_tools.py:215-235 (helper)

  Helper function that processes individual mailbox deletion: validates input, parses email target, calls MailboxService.delete_mailbox, and logs the operation.

  @bulk_processor_with_schema(MailboxDeleteRequest)
  async def process_delete_mailbox(
      validated_item: MailboxDeleteRequest, ctx: Context
  ) -> Dict[str, Any]:
      """Process a single mailbox deletion with Pydantic validation"""
      # Use validated Pydantic model directly - all validation already done
      target = validated_item.target
  
      # Parse target
      parsed = parse_email_target(target)
      domain, local_part = parsed[0]
      email_address = format_email_address(domain, local_part)
  
      await ctx.warning(f"🗑️ DESTRUCTIVE: Deleting mailbox {email_address}")
  
      service = get_service_factory().mailbox_service()
      await service.delete_mailbox(domain, local_part)
  
      await log_operation_success(ctx, "Deleted mailbox", email_address)
      return {"deleted": email_address, "success": True}

• migadu_mcp/utils/schemas.py:119-123 (schema)

  Pydantic model used for input validation of delete_mailbox requests, requiring a 'target' field (email or local part).

  class MailboxDeleteRequest(BaseModel):
      """Request schema for deleting a mailbox"""
  
      target: str = Field(..., description="Email address or local part")

• migadu_mcp/services/mailbox_service.py:107-116 (helper)

  Service layer method that executes the actual Migadu API DELETE request to remove the mailbox.

  async def delete_mailbox(self, domain: str, local_part: str) -> Dict[str, Any]:
      """Permanently delete a mailbox and all stored messages with API bug handling.
  
      Note: Due to Migadu API bug, successful deletions may return HTTP 500 errors.
      The operation actually succeeds despite the error response.
      """
      return await self.client.request(
          "DELETE", f"/domains/{domain}/mailboxes/{local_part}"
      )

• migadu_mcp/main.py:7-21 (registration)

  Registration of mailbox tools (including delete_mailbox) by calling register_mailbox_tools on the FastMCP instance in the main server initialization.

  from migadu_mcp.tools.mailbox_tools import register_mailbox_tools
  from migadu_mcp.tools.identity_tools import register_identity_tools
  from migadu_mcp.tools.alias_tools import register_alias_tools
  from migadu_mcp.tools.rewrite_tools import register_rewrite_tools
  from migadu_mcp.tools.resource_tools import register_resources
  
  
  # Initialize FastMCP server
  mcp: FastMCP = FastMCP("Migadu Mailbox Manager")
  
  
  def initialize_server():
      """Initialize the MCP server with all tools and resources"""
      # Register all tools
      register_mailbox_tools(mcp)