Migadu MCP Server

Instructions

Implementation Reference

• migadu_mcp/tools/mailbox_tools.py:196-213 (handler)

  Primary MCP tool handler for 'update_mailbox'. Dispatches bulk updates to process_update_mailbox helper with logging.

  @mcp.tool(
      annotations={
          "readOnlyHint": False,
          "destructiveHint": False,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  async def update_mailbox(
      updates: List[Dict[str, Any]], ctx: Context
  ) -> Dict[str, Any]:
      """Update mailbox settings. List of dicts with: target (required), name (optional), may_send (optional), may_receive (optional), may_access_imap (optional), may_access_pop3 (optional), spam_action (optional), spam_aggressiveness (optional)."""
      count = len(list(ensure_iterable(updates)))
      await log_bulk_operation_start(ctx, "Updating", count, "mailbox")
  
      result = await process_update_mailbox(updates, ctx)
      await log_bulk_operation_result(ctx, "Mailbox update", result, "mailbox")
      return result

• migadu_mcp/utils/schemas.py:96-117 (schema)

  Pydantic input schema for mailbox update requests, validated by bulk_processor_with_schema decorator.

  class MailboxUpdateRequest(BaseModel):
      """Request schema for updating a mailbox"""
  
      target: str = Field(..., description="Email address or local part")
      name: Optional[str] = Field(None, description="Update display name")
      may_send: Optional[bool] = Field(None, description="Allow/deny sending emails")
      may_receive: Optional[bool] = Field(None, description="Allow/deny receiving emails")
      may_access_imap: Optional[bool] = Field(None, description="Allow/deny IMAP access")
      may_access_pop3: Optional[bool] = Field(None, description="Allow/deny POP3 access")
      may_access_managesieve: Optional[bool] = Field(
          None, description="Allow/deny ManageSieve access"
      )
      spam_action: Optional[SpamAction] = Field(None, description="Spam handling action")
      spam_aggressiveness: Optional[SpamAggressiveness] = Field(
          None, description="Spam filtering sensitivity"
      )
      sender_denylist: Optional[str] = Field(None, description="Sender denylist rules")
      sender_allowlist: Optional[str] = Field(None, description="Sender allowlist rules")
      recipient_denylist: Optional[str] = Field(
          None, description="Recipient denylist rules"
      )

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

  Tool registration call in main.py that registers the update_mailbox handler via register_mailbox_tools.

  register_mailbox_tools(mcp)

• migadu_mcp/tools/mailbox_tools.py:158-195 (helper)

  Core processing logic for individual mailbox updates, including validation, parsing, service call, and logging.

  @bulk_processor_with_schema(MailboxUpdateRequest)
  async def process_update_mailbox(
      validated_item: MailboxUpdateRequest, ctx: Context
  ) -> Dict[str, Any]:
      """Process a single mailbox update with Pydantic validation"""
      # Use validated Pydantic model directly - all validation already done
      target = validated_item.target
      name = validated_item.name
      may_send = validated_item.may_send
      may_receive = validated_item.may_receive
      may_access_imap = validated_item.may_access_imap
      may_access_pop3 = validated_item.may_access_pop3
      spam_action = validated_item.spam_action
      spam_aggressiveness = validated_item.spam_aggressiveness
  
      # Parse target
      parsed = parse_email_target(target)
      domain, local_part = parsed[0]
      email_address = format_email_address(domain, local_part)
  
      await log_operation_start(ctx, "Updating mailbox", email_address)
  
      service = get_service_factory().mailbox_service()
      result = await service.update_mailbox(
          domain,
          local_part,
          name,
          may_send,
          may_receive,
          may_access_imap,
          may_access_pop3,
          spam_action,
          spam_aggressiveness,
      )
  
      await log_operation_success(ctx, "Updated mailbox", email_address)
      return {"mailbox": result, "email_address": email_address, "success": True}

• migadu_mcp/services/mailbox_service.py:70-105 (helper)

  Backend service method that performs the actual API call to update mailbox settings on Migadu.

  async def update_mailbox(
      self,
      domain: str,
      local_part: str,
      name: Optional[str] = None,
      may_send: Optional[bool] = None,
      may_receive: Optional[bool] = None,
      may_access_imap: Optional[bool] = None,
      may_access_pop3: Optional[bool] = None,
      spam_action: Optional[str] = None,
      spam_aggressiveness: Optional[str] = None,
  ) -> Dict[str, Any]:
      """Modify configuration settings for an existing mailbox including permissions and spam filtering.
  
      Allows selective updates to display name, send/receive permissions, protocol access controls,
      and spam filtering behavior without affecting other mailbox settings.
      """
      data: Dict[str, Any] = {}
      if name is not None:
          data["name"] = name
      if may_send is not None:
          data["may_send"] = may_send
      if may_receive is not None:
          data["may_receive"] = may_receive
      if may_access_imap is not None:
          data["may_access_imap"] = may_access_imap
      if may_access_pop3 is not None:
          data["may_access_pop3"] = may_access_pop3
      if spam_action is not None:
          data["spam_action"] = spam_action
      if spam_aggressiveness is not None:
          data["spam_aggressiveness"] = spam_aggressiveness
  
      return await self.client.request(
          "PUT", f"/domains/{domain}/mailboxes/{local_part}", json=data
      )