mcp-email-server

IMAP and SMTP via MCP Server

• Github repository: https://github.com/wh1isper/mcp-email-server/
• Documentation https://mcp-email-server.wh1isper.top/

Installation

Manual Installation

We recommend using uv to manage your environment.

Try uvx mcp-email-server@latest ui to config, and use following configuration for mcp client:

{
  "mcpServers": {
    "mcp-email-server": {
      "command": "uvx",
      "args": ["mcp-email-server@latest", "stdio"]
    }
  }
}

This package is available on PyPI, so you can install it using pip install mcp-email-server

After that, configure your email server using the ui: mcp-email-server ui

Credential Storage

Accounts added via the UI or the add_email_account tool are persisted to a TOML file at ~/.config/mcp-email-server/config.toml. On first use, an existing config from the previous ~/.config/zerolib/mcp_email_server/config.toml location is copied automatically when the new file does not exist. Where the actual passwords/API keys live depends on credential_storage (also settable via MCP_EMAIL_SERVER_CREDENTIAL_STORAGE), one of:

• auto (default): store credentials in the OS keyring — macOS Keychain, Linux Secret Service (GNOME Keyring / KWallet) — when a usable backend is detected; otherwise fall back to the plaintext TOML file (0o600 permissions, owner-only). Falls back automatically on headless Linux, containers, or any environment without a D-Bus session.
• keyring: require the OS keyring; fail loudly instead of silently falling back if no backend is usable.
• plaintext: never touch the keyring. Useful for containers, CI, or if you simply prefer a portable config file.

When credentials are keyring-backed, the TOML file stores only a placeholder (__KEYRING__) and non-secret metadata — the real secret lives in the OS keyring under service mcp-email-server, one entry per <account_name>:<incoming|outgoing|api_key> (viewable in Keychain Access on macOS, or Seahorse on Linux).

Migrating an existing config between storage modes:

mcp-email-server migrate-credentials --to keyring    # move plaintext secrets into the OS keyring
mcp-email-server migrate-credentials --to plaintext  # move keyring secrets back into the TOML file

Migration also happens implicitly: any time you add/edit an account while credential_storage is auto or keyring with a usable backend, that account's secrets move into the keyring on the next save. If MCP_EMAIL_SERVER_CREDENTIAL_STORAGE is active during a save, its effective mode is persisted too, keeping the mode marker consistent with the credential representation written to the same file.

Failure modes & troubleshooting

• Server won't start / UI won't load accounts, keychain-related error: the OS keyring is locked or unreachable. This is expected if credentials are keyring-backed — the secret simply isn't in the config file. Unlock your keychain, or run mcp-email-server migrate-credentials --to plaintext if you'd rather not depend on it.
• credential_storage is 'plaintext' but the config references keyring-stored credentials: run migrate-credentials --to plaintext, or unset MCP_EMAIL_SERVER_CREDENTIAL_STORAGE / the credential_storage setting so the config can resolve them from the keyring instead.
• macOS Keychain access prompt, or the server can't read a secret it wrote earlier: Keychain ACLs are per-application. If the server is spawned via uvx (as in the Claude Desktop config above), a fresh uvx resolution can present a different binary path than the one that stored the secret, triggering a "Keychain wants to use a password" prompt. Choose "Always Allow" the first time this happens.
• A migration seems to have had no effect: if MCP_EMAIL_SERVER_CREDENTIAL_STORAGE is set in your environment, it takes precedence over whatever migrate-credentials --to ... just wrote to the file on every subsequent run. Unset it, or keep it in sync with your intended mode.

Known limitations

• Non-POSIX (Windows) file permissions: the 0o600 owner-only guarantee on the plaintext TOML is enforced only on POSIX systems. On Windows the file is written without an owner-restricted ACL, so prefer keyring mode (Windows Credential Locker) there when secrets must not be readable by other accounts.
• auto/keyring trusts whatever keyring backend is active: usability is decided by a live set/get round-trip, not by the backend's storage guarantees. A third-party keyring plugin that persists secrets in plaintext would pass that probe. If you install custom keyring backends, verify the active one (keyring --list-backends) stores secrets securely.
• Keyring and TOML writes are not transactional: a save pushes secrets to the keyring and then rewrites the TOML. The TOML rewrite is atomic on its own (temp file + os.replace), but a crash between the two steps can leave a keyring entry with no matching config reference (an orphaned secret), or a config reference whose keyring write partly failed. A plaintext migration reports keyring entries it could not remove so you can clean them up manually.

Environment Variable Configuration

You can also configure the email server using environment variables, which is particularly useful for CI/CD environments like Jenkins. mcp-email-server supports both UI configuration (via TOML file) and environment variables, with environment variables taking precedence.

{
  "mcpServers": {
    "mcp-email-server": {
      "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