Migadu MCP Server

Instructions

Implementation Reference

• migadu_mcp/tools/mailbox_tools.py:34-69 (handler)

  The MCP tool handler function for 'list_mailboxes', decorated with @mcp.tool(). Handles domain resolution, logging, and delegates to the mailbox service.

  @mcp.tool(
      annotations={
          "readOnlyHint": True,
          "idempotentHint": True,
          "openWorldHint": True,
      },
  )
  @with_context_protection(max_tokens=2000)
  async def list_mailboxes(ctx: Context, domain: str | None = None) -> Dict[str, Any]:
      """List email mailboxes for domain. Returns summary with statistics and samples.
  
      Args:
          domain: Domain name. Uses MIGADU_DOMAIN if not provided.
  
      Returns:
          JSON object with mailbox summary and statistics
      """
      if domain is None:
          from migadu_mcp.config import get_config
  
          config = get_config()
          domain = config.get_default_domain()
          if not domain:
              raise ValueError("No domain provided and MIGADU_DOMAIN not configured")
  
      await log_operation_start(ctx, "Listing mailboxes", domain)
      try:
          service = get_service_factory().mailbox_service()
          result = await service.list_mailboxes(domain)
          count = len(result.get("mailboxes", []))
          await log_operation_success(ctx, "Listed mailboxes", domain, count)
          return result
      except Exception as e:
          await log_operation_error(ctx, "List mailboxes", domain, str(e))
          raise

• migadu_mcp/main.py:18-25 (registration)

  The initialization function where register_mailbox_tools(mcp) is called to register the list_mailboxes tool (line 21).

  def initialize_server():
      """Initialize the MCP server with all tools and resources"""
      # Register all tools
      register_mailbox_tools(mcp)
      register_identity_tools(mcp)
      register_alias_tools(mcp)
      register_rewrite_tools(mcp)
      register_resources(mcp)

• migadu_mcp/services/mailbox_service.py:21-28 (helper)

  The MailboxService method that implements the core logic by making the API request to list mailboxes for the given domain.

  async def list_mailboxes(self, domain: str) -> Dict[str, Any]:
      """Retrieve all email mailboxes configured for a domain with complete configuration details.
  
      Returns comprehensive information for each mailbox including permissions, spam settings,
      autoresponder configuration, and security options for domain-wide auditing and management.
      """
      return await self.client.request("GET", f"/domains/{domain}/mailboxes")