mcp-email-server 0.5.2__py3-none-any.whl

mcp_email_server/app.py

@@ -0,0 +1,206 @@
+from datetime import datetime
+from typing import Annotated, Literal
+
+from mcp.server.fastmcp import FastMCP
+from pydantic import Field
+
+from mcp_email_server.config import (
+    AccountAttributes,
+    EmailSettings,
+    ProviderSettings,
+    get_settings,
+)
+from mcp_email_server.emails.dispatcher import dispatch_handler
+from mcp_email_server.emails.models import (
+    AttachmentDownloadResponse,
+    EmailContentBatchResponse,
+    EmailMetadataPageResponse,
+)
+
+mcp = FastMCP("email")
+
+
+@mcp.resource("email://{account_name}")
+async def get_account(account_name: str) -> EmailSettings | ProviderSettings | None:
+    settings = get_settings()
+    return settings.get_account(account_name, masked=True)
+
+
+@mcp.tool(description="List all configured email accounts with masked credentials.")
+async def list_available_accounts() -> list[AccountAttributes]:
+    settings = get_settings()
+    return [account.masked() for account in settings.get_accounts()]
+
+
+@mcp.tool(description="Add a new email account configuration to the settings.")
+async def add_email_account(email: EmailSettings) -> str:
+    settings = get_settings()
+    settings.add_email(email)
+    settings.store()
+    return f"Successfully added email account '{email.account_name}'"
+
+
+@mcp.tool(
+    description="List email metadata (email_id, subject, sender, recipients, date) without body content. Returns email_id for use with get_emails_content."
+)
+async def list_emails_metadata(
+    account_name: Annotated[str, Field(description="The name of the email account.")],
+    page: Annotated[
+        int,
+        Field(default=1, description="The page number to retrieve (starting from 1)."),
+    ] = 1,
+    page_size: Annotated[int, Field(default=10, description="The number of emails to retrieve per page.")] = 10,
+    before: Annotated[
+        datetime | None,
+        Field(default=None, description="Retrieve emails before this datetime (UTC)."),
+    ] = None,
+    since: Annotated[
+        datetime | None,
+        Field(default=None, description="Retrieve emails since this datetime (UTC)."),
+    ] = None,
+    subject: Annotated[str | None, Field(default=None, description="Filter emails by subject.")] = None,
+    from_address: Annotated[str | None, Field(default=None, description="Filter emails by sender address.")] = None,
+    to_address: Annotated[
+        str | None,
+        Field(default=None, description="Filter emails by recipient address."),
+    ] = None,
+    order: Annotated[
+        Literal["asc", "desc"],
+        Field(default=None, description="Order emails by field. `asc` or `desc`."),
+    ] = "desc",
+    mailbox: Annotated[str, Field(default="INBOX", description="The mailbox to retrieve emails from.")] = "INBOX",
+) -> EmailMetadataPageResponse:
+    handler = dispatch_handler(account_name)
+
+    return await handler.get_emails_metadata(
+        page=page,
+        page_size=page_size,
+        before=before,
+        since=since,
+        subject=subject,
+        from_address=from_address,
+        to_address=to_address,
+        order=order,
+        mailbox=mailbox,
+    )
+
+
+@mcp.tool(
+    description="Get the full content (including body) of one or more emails by their email_id. Use list_emails_metadata first to get the email_id."
+)
+async def get_emails_content(
+    account_name: Annotated[str, Field(description="The name of the email account.")],
+    email_ids: Annotated[
+        list[str],
+        Field(
+            description="List of email_id to retrieve (obtained from list_emails_metadata). Can be a single email_id or multiple email_ids."
+        ),
+    ],
+    mailbox: Annotated[str, Field(default="INBOX", description="The mailbox to retrieve emails from.")] = "INBOX",
+) -> EmailContentBatchResponse:
+    handler = dispatch_handler(account_name)
+    return await handler.get_emails_content(email_ids, mailbox)
+
+
+@mcp.tool(
+    description="Send an email using the specified account. Supports replying to emails with proper threading when in_reply_to is provided.",
+)
+async def send_email(
+    account_name: Annotated[str, Field(description="The name of the email account to send from.")],
+    recipients: Annotated[list[str], Field(description="A list of recipient email addresses.")],
+    subject: Annotated[str, Field(description="The subject of the email.")],
+    body: Annotated[str, Field(description="The body of the email.")],
+    cc: Annotated[
+        list[str] | None,
+        Field(default=None, description="A list of CC email addresses."),
+    ] = None,
+    bcc: Annotated[
+        list[str] | None,
+        Field(default=None, description="A list of BCC email addresses."),
+    ] = None,
+    html: Annotated[
+        bool,
+        Field(default=False, description="Whether to send the email as HTML (True) or plain text (False)."),
+    ] = False,
+    attachments: Annotated[
+        list[str] | None,
+        Field(
+            default=None,
+            description="A list of absolute file paths to attach to the email. Supports common file types (documents, images, archives, etc.).",
+        ),
+    ] = None,
+    in_reply_to: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Message-ID of the email being replied to. Enables proper threading in email clients.",
+        ),
+    ] = None,
+    references: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Space-separated Message-IDs for the thread chain. Usually includes in_reply_to plus ancestors.",
+        ),
+    ] = None,
+) -> str:
+    handler = dispatch_handler(account_name)
+    await handler.send_email(
+        recipients,
+        subject,
+        body,
+        cc,
+        bcc,
+        html,
+        attachments,
+        in_reply_to,
+        references,
+    )
+    recipient_str = ", ".join(recipients)
+    attachment_info = f" with {len(attachments)} attachment(s)" if attachments else ""
+    return f"Email sent successfully to {recipient_str}{attachment_info}"
+
+
+@mcp.tool(
+    description="Delete one or more emails by their email_id. Use list_emails_metadata first to get the email_id."
+)
+async def delete_emails(
+    account_name: Annotated[str, Field(description="The name of the email account.")],
+    email_ids: Annotated[
+        list[str],
+        Field(description="List of email_id to delete (obtained from list_emails_metadata)."),
+    ],
+    mailbox: Annotated[str, Field(default="INBOX", description="The mailbox to delete emails from.")] = "INBOX",
+) -> str:
+    handler = dispatch_handler(account_name)
+    deleted_ids, failed_ids = await handler.delete_emails(email_ids, mailbox)
+
+    result = f"Successfully deleted {len(deleted_ids)} email(s)"
+    if failed_ids:
+        result += f", failed to delete {len(failed_ids)} email(s): {', '.join(failed_ids)}"
+    return result
+
+
+@mcp.tool(
+    description="Download an email attachment and save it to the specified path. This feature must be explicitly enabled in settings (enable_attachment_download=true) due to security considerations.",
+)
+async def download_attachment(
+    account_name: Annotated[str, Field(description="The name of the email account.")],
+    email_id: Annotated[
+        str, Field(description="The email ID (obtained from list_emails_metadata or get_emails_content).")
+    ],
+    attachment_name: Annotated[
+        str, Field(description="The name of the attachment to download (as shown in the attachments list).")
+    ],
+    save_path: Annotated[str, Field(description="The absolute path where the attachment should be saved.")],
+    mailbox: Annotated[str, Field(description="The mailbox to search in (default: INBOX).")] = "INBOX",
+) -> AttachmentDownloadResponse:
+    settings = get_settings()
+    if not settings.enable_attachment_download:
+        msg = (
+            "Attachment download is disabled. Set 'enable_attachment_download=true' in settings to enable this feature."
+        )
+        raise PermissionError(msg)
+
+    handler = dispatch_handler(account_name)
+    return await handler.download_attachment(email_id, attachment_name, save_path, mailbox)

mcp_email_server/cli.py

@@ -0,0 +1,50 @@
+import os
+
+import typer
+
+from mcp_email_server.app import mcp
+from mcp_email_server.config import delete_settings
+
+app = typer.Typer()
+
+
+@app.command()
+def stdio():
+    mcp.run(transport="stdio")
+
+
+@app.command()
+def sse(
+    host: str = "localhost",
+    port: int = 9557,
+):
+    mcp.settings.host = host
+    mcp.settings.port = port
+    mcp.run(transport="sse")
+
+
+@app.command()
+def streamable_http(
+    host: str = os.environ.get("MCP_HOST", "localhost"),
+    port: int = os.environ.get("MCP_PORT", 9557),
+):
+    mcp.settings.host = host
+    mcp.settings.port = port
+    mcp.run(transport="streamable-http")
+
+
+@app.command()
+def ui():
+    from mcp_email_server.ui import main as ui_main
+
+    ui_main()
+
+
+@app.command()
+def reset():
+    delete_settings()
+    typer.echo("✅ Config reset")
+
+
+if __name__ == "__main__":
+    app(["stdio"])

mcp_email_server/config.py

@@ -0,0 +1,349 @@
+from __future__ import annotations
+
+import datetime
+import os
+from pathlib import Path
+from typing import Any
+from zoneinfo import ZoneInfo
+
+import tomli_w
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, model_validator
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+)
+
+from mcp_email_server.log import logger
+
+DEFAILT_CONFIG_PATH = "~/.config/zerolib/mcp_email_server/config.toml"
+
+CONFIG_PATH = Path(os.getenv("MCP_EMAIL_SERVER_CONFIG_PATH", DEFAILT_CONFIG_PATH)).expanduser().resolve()
+
+
+class EmailServer(BaseModel):
+    user_name: str
+    password: str
+    host: str
+    port: int
+    use_ssl: bool = True  # Usually port 465
+    start_ssl: bool = False  # Usually port 587
+
+    def masked(self) -> EmailServer:
+        return self.model_copy(update={"password": "********"})
+
+
+class AccountAttributes(BaseModel):
+    model_config = ConfigDict(json_encoders={datetime.datetime: lambda v: v.isoformat()})
+    account_name: str
+    description: str = ""
+    created_at: datetime.datetime = Field(default_factory=lambda: datetime.datetime.now(ZoneInfo("UTC")))
+    updated_at: datetime.datetime = Field(default_factory=lambda: datetime.datetime.now(ZoneInfo("UTC")))
+
+    @model_validator(mode="after")
+    @classmethod
+    def update_updated_at(cls, obj: AccountAttributes) -> AccountAttributes:
+        """Update updated_at field."""
+        # must disable validation to avoid infinite loop
+        obj.model_config["validate_assignment"] = False
+
+        # update updated_at field
+        obj.updated_at = datetime.datetime.now(ZoneInfo("UTC"))
+
+        # enable validation again
+        obj.model_config["validate_assignment"] = True
+        return obj
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, AccountAttributes):
+            return NotImplemented
+        return self.model_dump(exclude={"created_at", "updated_at"}) == other.model_dump(
+            exclude={"created_at", "updated_at"}
+        )
+
+    @field_serializer("created_at", "updated_at")
+    def serialize_datetime(self, v: datetime.datetime) -> str:
+        return v.isoformat()
+
+    def masked(self) -> AccountAttributes:
+        return self.model_copy()
+
+
+class EmailSettings(AccountAttributes):
+    full_name: str
+    email_address: str
+    incoming: EmailServer
+    outgoing: EmailServer
+    save_to_sent: bool = True  # Save sent emails to IMAP Sent folder
+    sent_folder_name: str | None = None  # Override Sent folder name (auto-detect if None)
+
+    @classmethod
+    def init(
+        cls,
+        *,
+        account_name: str,
+        full_name: str,
+        email_address: str,
+        user_name: str,
+        password: str,
+        imap_host: str,
+        smtp_host: str,
+        imap_user_name: str | None = None,
+        imap_password: str | None = None,
+        imap_port: int = 993,
+        imap_ssl: bool = True,
+        smtp_port: int = 465,
+        smtp_ssl: bool = True,
+        smtp_start_ssl: bool = False,
+        smtp_user_name: str | None = None,
+        smtp_password: str | None = None,
+        save_to_sent: bool = True,
+        sent_folder_name: str | None = None,
+    ) -> EmailSettings:
+        return cls(
+            account_name=account_name,
+            full_name=full_name,
+            email_address=email_address,
+            incoming=EmailServer(
+                user_name=imap_user_name or user_name,
+                password=imap_password or password,
+                host=imap_host,
+                port=imap_port,
+                use_ssl=imap_ssl,
+            ),
+            outgoing=EmailServer(
+                user_name=smtp_user_name or user_name,
+                password=smtp_password or password,
+                host=smtp_host,
+                port=smtp_port,
+                use_ssl=smtp_ssl,
+                start_ssl=smtp_start_ssl,
+            ),
+            save_to_sent=save_to_sent,
+            sent_folder_name=sent_folder_name,
+        )
+
+    @classmethod
+    def from_env(cls) -> EmailSettings | None:
+        """Create EmailSettings from environment variables.
+
+        Expected environment variables:
+        - MCP_EMAIL_SERVER_ACCOUNT_NAME (default: "default")
+        - MCP_EMAIL_SERVER_FULL_NAME
+        - MCP_EMAIL_SERVER_EMAIL_ADDRESS
+        - MCP_EMAIL_SERVER_USER_NAME
+        - MCP_EMAIL_SERVER_PASSWORD
+        - MCP_EMAIL_SERVER_IMAP_HOST
+        - MCP_EMAIL_SERVER_IMAP_PORT (default: 993)
+        - MCP_EMAIL_SERVER_IMAP_SSL (default: true)
+        - MCP_EMAIL_SERVER_SMTP_HOST
+        - MCP_EMAIL_SERVER_SMTP_PORT (default: 465)
+        - MCP_EMAIL_SERVER_SMTP_SSL (default: true)
+        - MCP_EMAIL_SERVER_SMTP_START_SSL (default: false)
+        - MCP_EMAIL_SERVER_SAVE_TO_SENT (default: true)
+        - MCP_EMAIL_SERVER_SENT_FOLDER_NAME (default: auto-detect)
+        """
+        # Check if minimum required environment variables are set
+        email_address = os.getenv("MCP_EMAIL_SERVER_EMAIL_ADDRESS")
+        password = os.getenv("MCP_EMAIL_SERVER_PASSWORD")
+
+        if not email_address or not password:
+            return None
+
+        # Parse boolean values
+        def parse_bool(value: str | None, default: bool = True) -> bool:
+            if value is None:
+                return default
+            return value.lower() in ("true", "1", "yes", "on")
+
+        # Get all environment variables with defaults
+        account_name = os.getenv("MCP_EMAIL_SERVER_ACCOUNT_NAME", "default")
+        full_name = os.getenv("MCP_EMAIL_SERVER_FULL_NAME", email_address.split("@")[0])
+        user_name = os.getenv("MCP_EMAIL_SERVER_USER_NAME", email_address)
+        imap_host = os.getenv("MCP_EMAIL_SERVER_IMAP_HOST")
+        smtp_host = os.getenv("MCP_EMAIL_SERVER_SMTP_HOST")
+
+        # Required fields check
+        if not imap_host or not smtp_host:
+            logger.warning("Missing required email configuration environment variables (IMAP_HOST or SMTP_HOST)")
+            return None
+
+        try:
+            return cls.init(
+                account_name=account_name,
+                full_name=full_name,
+                email_address=email_address,
+                user_name=user_name,
+                password=password,
+                imap_host=imap_host,
+                imap_port=int(os.getenv("MCP_EMAIL_SERVER_IMAP_PORT", "993")),
+                imap_ssl=parse_bool(os.getenv("MCP_EMAIL_SERVER_IMAP_SSL"), True),
+                smtp_host=smtp_host,
+                smtp_port=int(os.getenv("MCP_EMAIL_SERVER_SMTP_PORT", "465")),
+                smtp_ssl=parse_bool(os.getenv("MCP_EMAIL_SERVER_SMTP_SSL"), True),
+                smtp_start_ssl=parse_bool(os.getenv("MCP_EMAIL_SERVER_SMTP_START_SSL"), False),
+                smtp_user_name=os.getenv("MCP_EMAIL_SERVER_SMTP_USER_NAME", user_name),
+                smtp_password=os.getenv("MCP_EMAIL_SERVER_SMTP_PASSWORD", password),
+                imap_user_name=os.getenv("MCP_EMAIL_SERVER_IMAP_USER_NAME", user_name),
+                imap_password=os.getenv("MCP_EMAIL_SERVER_IMAP_PASSWORD", password),
+                save_to_sent=parse_bool(os.getenv("MCP_EMAIL_SERVER_SAVE_TO_SENT"), True),
+                sent_folder_name=os.getenv("MCP_EMAIL_SERVER_SENT_FOLDER_NAME"),
+            )
+        except (ValueError, TypeError) as e:
+            logger.error(f"Failed to create email settings from environment variables: {e}")
+            return None
+
+    def masked(self) -> EmailSettings:
+        return self.model_copy(
+            update={
+                "incoming": self.incoming.masked(),
+                "outgoing": self.outgoing.masked(),
+            }
+        )
+
+
+class ProviderSettings(AccountAttributes):
+    provider_name: str
+    api_key: str
+
+    def masked(self) -> AccountAttributes:
+        return self.model_copy(update={"api_key": "********"})
+
+
+def _parse_bool_env(value: str | None, default: bool = False) -> bool:
+    """Parse boolean value from environment variable."""
+    if value is None:
+        return default
+    return value.lower() in ("true", "1", "yes", "on")
+
+
+class Settings(BaseSettings):
+    emails: list[EmailSettings] = []
+    providers: list[ProviderSettings] = []
+    db_location: str = CONFIG_PATH.with_name("db.sqlite3").as_posix()
+    enable_attachment_download: bool = False
+
+    model_config = SettingsConfigDict(toml_file=CONFIG_PATH, validate_assignment=True, revalidate_instances="always")
+
+    def __init__(self, **data: Any) -> None:
+        """Initialize Settings with support for environment variables."""
+        super().__init__(**data)
+
+        # Check for enable_attachment_download from environment variable
+        env_enable_attachment = os.getenv("MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD")
+        if env_enable_attachment is not None:
+            self.enable_attachment_download = _parse_bool_env(env_enable_attachment, False)
+            logger.info(f"Set enable_attachment_download={self.enable_attachment_download} from environment variable")
+
+        # Check for email configuration from environment variables
+        env_email = EmailSettings.from_env()
+        if env_email:
+            # Check if this account already exists (from TOML)
+            existing_account = None
+            for i, email in enumerate(self.emails):
+                if email.account_name == env_email.account_name:
+                    existing_account = i
+                    break
+
+            if existing_account is not None:
+                # Replace existing account with env configuration
+                self.emails[existing_account] = env_email
+                logger.info(f"Overriding email account '{env_email.account_name}' with environment variables")
+            else:
+                # Add new account from env
+                self.emails.insert(0, env_email)
+                logger.info(f"Added email account '{env_email.account_name}' from environment variables")
+
+    def add_email(self, email: EmailSettings) -> None:
+        """Use re-assigned for validation to work."""
+        self.emails = [email, *self.emails]
+
+    def add_provider(self, provider: ProviderSettings) -> None:
+        """Use re-assigned for validation to work."""
+        self.providers = [provider, *self.providers]
+
+    def delete_email(self, account_name: str) -> None:
+        """Use re-assigned for validation to work."""
+        self.emails = [email for email in self.emails if email.account_name != account_name]
+
+    def delete_provider(self, account_name: str) -> None:
+        """Use re-assigned for validation to work."""
+        self.providers = [provider for provider in self.providers if provider.account_name != account_name]
+
+    def get_account(self, account_name: str, masked: bool = False) -> EmailSettings | ProviderSettings | None:
+        for email in self.emails:
+            if email.account_name == account_name:
+                return email if not masked else email.masked()
+        for provider in self.providers:
+            if provider.account_name == account_name:
+                return provider if not masked else provider.masked()
+        return None
+
+    def get_accounts(self, masked: bool = False) -> list[EmailSettings | ProviderSettings]:
+        accounts = self.emails + self.providers
+        if masked:
+            return [account.masked() for account in accounts]
+        return accounts
+
+    @model_validator(mode="after")
+    @classmethod
+    def check_unique_account_names(cls, obj: Settings) -> Settings:
+        account_names = set()
+        for email in obj.emails:
+            if email.account_name in account_names:
+                raise ValueError(f"Duplicate account name {email.account_name}")
+            account_names.add(email.account_name)
+        for provider in obj.providers:
+            if provider.account_name in account_names:
+                raise ValueError(f"Duplicate account name {provider.account_name}")
+            account_names.add(provider.account_name)
+
+        return obj
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        return (TomlConfigSettingsSource(settings_cls),)
+
+    def _to_toml(self) -> str:
+        data = self.model_dump(exclude_none=True)
+        return tomli_w.dumps(data)
+
+    def store(self) -> None:
+        toml_file = self.model_config["toml_file"]
+        toml_file.parent.mkdir(parents=True, exist_ok=True)
+        toml_file.write_text(self._to_toml())
+        logger.info(f"Settings stored in {toml_file}")
+
+
+_settings = None
+
+
+def get_settings(reload: bool = False) -> Settings:
+    global _settings
+    if not _settings or reload:
+        logger.info(f"Loading settings from {CONFIG_PATH}")
+        _settings = Settings()
+    return _settings
+
+
+def store_settings(settings: Settings | None = None) -> None:
+    if not settings:
+        settings = get_settings()
+    settings.store()
+    return
+
+
+def delete_settings() -> None:
+    if not CONFIG_PATH.exists():
+        logger.info(f"Settings file {CONFIG_PATH} does not exist")
+        return
+    CONFIG_PATH.unlink()
+    logger.info(f"Deleted settings file {CONFIG_PATH}")

mcp_email_server/emails/__init__.py

@@ -0,0 +1,77 @@
+import abc
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from mcp_email_server.emails.models import (
+        AttachmentDownloadResponse,
+        EmailContentBatchResponse,
+        EmailMetadataPageResponse,
+    )
+
+
+class EmailHandler(abc.ABC):
+    @abc.abstractmethod
+    async def get_emails_metadata(
+        self,
+        page: int = 1,
+        page_size: int = 10,
+        before: datetime | None = None,
+        since: datetime | None = None,
+        subject: str | None = None,
+        from_address: str | None = None,
+        to_address: str | None = None,
+        order: str = "desc",
+        mailbox: str = "INBOX",
+    ) -> "EmailMetadataPageResponse":
+        """
+        Get email metadata only (without body content) for better performance
+        """
+
+    @abc.abstractmethod
+    async def get_emails_content(self, email_ids: list[str], mailbox: str = "INBOX") -> "EmailContentBatchResponse":
+        """
+        Get full content (including body) of multiple emails by their email IDs (IMAP UIDs)
+        """
+
+    @abc.abstractmethod
+    async def send_email(
+        self,
+        recipients: list[str],
+        subject: str,
+        body: str,
+        cc: list[str] | None = None,
+        bcc: list[str] | None = None,
+        html: bool = False,
+        attachments: list[str] | None = None,
+    ) -> None:
+        """
+        Send email
+        """
+
+    @abc.abstractmethod
+    async def delete_emails(self, email_ids: list[str], mailbox: str = "INBOX") -> tuple[list[str], list[str]]:
+        """
+        Delete emails by their IDs. Returns (deleted_ids, failed_ids)
+        """
+
+    @abc.abstractmethod
+    async def download_attachment(
+        self,
+        email_id: str,
+        attachment_name: str,
+        save_path: str,
+        mailbox: str = "INBOX",
+    ) -> "AttachmentDownloadResponse":
+        """
+        Download an email attachment and save it to the specified path.
+
+        Args:
+            email_id: The UID of the email containing the attachment.
+            attachment_name: The filename of the attachment to download.
+            save_path: The local path where the attachment will be saved.
+            mailbox: The mailbox to search in (default: "INBOX").
+
+        Returns:
+            AttachmentDownloadResponse with download result information.
+        """