Environment variable support for email server configuration (#48)

valimikayilov · pre-commit-ci[bot] · web-flow · commit a5627df73c39 · 2025-09-04T14:16:54.000+08:00
* Environment variable support for email server configuration * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Add comprehensive tests for environment variable configuration - Test missing email/password scenarios - Test missing IMAP/SMTP hosts with logger warnings - Test exception handling for invalid port values - Test Settings initialization with and without env vars - Test account override vs new account addition - Test boolean parsing for SSL settings - Test masked() method for security These tests ensure proper coverage of the environment variable configuration feature added for CI/CD deployments. * [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci * Fix linting issues in test_env_config_coverage.py - Add noqa comments for false positive password warnings - Fix formatting and trailing whitespace - Ensure file ends with newline --------- Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
diff --git a/README.md b/README.md
@@ -35,6 +35,54 @@ This package is available on PyPI, so you can install it using `pip install mcp-
 
 After that, configure your email server using the ui: `mcp-email-server ui`
 
+### Environment Variable Configuration
+
+You can also configure the email server using environment variables, which is particularly useful for CI/CD environments like Jenkins. zerolib-email supports both UI configuration (via TOML file) and environment variables, with environment variables taking precedence.
+
+```json
+{
+  "mcpServers": {
+    "zerolib-email": {
+      "command": "uvx",
+      "args": ["mcp-email-server@latest", "stdio"],
+      "env": {
+        "MCP_EMAIL_SERVER_ACCOUNT_NAME": "work",
+        "MCP_EMAIL_SERVER_FULL_NAME": "John Doe",
+        "MCP_EMAIL_SERVER_EMAIL_ADDRESS": "john@example.com",
+        "MCP_EMAIL_SERVER_USER_NAME": "john@example.com",
+        "MCP_EMAIL_SERVER_PASSWORD": "your_password",
+        "MCP_EMAIL_SERVER_IMAP_HOST": "imap.gmail.com",
+        "MCP_EMAIL_SERVER_IMAP_PORT": "993",
+        "MCP_EMAIL_SERVER_SMTP_HOST": "smtp.gmail.com",
+        "MCP_EMAIL_SERVER_SMTP_PORT": "465"
+      }
+    }
+  }
+}
+```
+
+#### Available Environment Variables
+
+| Variable                          | Description        | Default       | Required |
+| --------------------------------- | ------------------ | ------------- | -------- |
+| `MCP_EMAIL_SERVER_ACCOUNT_NAME`   | Account identifier | `"default"`   | No       |
+| `MCP_EMAIL_SERVER_FULL_NAME`      | Display name       | Email prefix  | No       |
+| `MCP_EMAIL_SERVER_EMAIL_ADDRESS`  | Email address      | -             | Yes      |
+| `MCP_EMAIL_SERVER_USER_NAME`      | Login username     | Same as email | No       |
+| `MCP_EMAIL_SERVER_PASSWORD`       | Email password     | -             | Yes      |
+| `MCP_EMAIL_SERVER_IMAP_HOST`      | IMAP server host   | -             | Yes      |
+| `MCP_EMAIL_SERVER_IMAP_PORT`      | IMAP server port   | `993`         | No       |
+| `MCP_EMAIL_SERVER_IMAP_SSL`       | Enable IMAP SSL    | `true`        | No       |
+| `MCP_EMAIL_SERVER_SMTP_HOST`      | SMTP server host   | -             | Yes      |
+| `MCP_EMAIL_SERVER_SMTP_PORT`      | SMTP server port   | `465`         | No       |
+| `MCP_EMAIL_SERVER_SMTP_SSL`       | Enable SMTP SSL    | `true`        | No       |
+| `MCP_EMAIL_SERVER_SMTP_START_SSL` | Enable STARTTLS    | `false`       | No       |
+
+For separate IMAP/SMTP credentials, you can also use:
+
+- `MCP_EMAIL_SERVER_IMAP_USER_NAME` / `MCP_EMAIL_SERVER_IMAP_PASSWORD`
+- `MCP_EMAIL_SERVER_SMTP_USER_NAME` / `MCP_EMAIL_SERVER_SMTP_PASSWORD`
+
 Then you can try it in [Claude Desktop](https://claude.ai/download). If you want to intergrate it with other mcp client, run `$which mcp-email-server` for the path and configure it in your client like:
 
 ```json
diff --git a/mcp_email_server/config.py b/mcp_email_server/config.py
@@ -3,6 +3,7 @@
 import datetime
 import os
 from pathlib import Path
+from typing import Any
 
 import tomli_w
 from pydantic import BaseModel, Field, model_validator
@@ -111,6 +112,72 @@ def init(
             ),
         )
 
+    @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)
+        """
+        # 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),
+            )
+        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={
@@ -135,6 +202,29 @@ class Settings(BaseSettings):
 
     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 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]
diff --git a/tests/test_env_config_coverage.py b/tests/test_env_config_coverage.py
