mcp-email-server

通过MCP服务器实现IMAP和SMTP

• Github仓库: https://github.com/ai-zerolab/mcp-email-server/
• 文档 https://ai-zerolab.github.io/mcp-email-server/

安装

手动安装

我们推荐使用uv来管理你的环境。

尝试使用uvx mcp-email-server@latest ui进行配置，并为mcp客户端使用以下配置：

{

  "mcpServers": {

    "zerolib-email": {

      "command": "uvx",

      "args": ["mcp-email-server@latest", "stdio"]

    }

  }

}

此包在PyPI上可用，因此你可以使用pip install mcp-email-server进行安装。

之后，使用UI配置你的邮件服务器：mcp-email-server ui

环境变量配置

你也可以使用环境变量来配置邮件服务器，这对于像Jenkins这样的CI/CD环境特别有用。zerolib-email支持UI配置（通过TOML文件）和环境变量配置，其中环境变量优先。

{

  "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"

      }

    }

  }

}

可用的环境变量

只读 IMAP 模式

SMTP 配置是可选的。当省略 MCP_EMAIL_SERVER_SMTP_HOST 时，账户将以只读模式运行，并且仅暴露读取/邮箱管理工具。如果所有配置的电子邮件账户都是只读的，则会隐藏如 send_email 和 save_to_mailbox 等外发撰写工具。

{

  "mcpServers": {

    "zerolib-email": {

      "command": "uvx",

      "args": ["mcp-email-server@latest", "stdio"],

      "env": {

        "MCP_EMAIL_SERVER_EMAIL_ADDRESS": "john@example.com",

        "MCP_EMAIL_SERVER_PASSWORD": "your_password",

        "MCP_EMAIL_SERVER_IMAP_HOST": "imap.gmail.com"

      }

    }

  }

}

HTTP 传输安全

HTTP 传输 (sse 和 streamable-http) 会验证请求的 Host 和 Origin 头以防止 DNS 重绑定攻击。默认情况下允许本地主机。对于 Docker 网络或反向代理，请明确配置预期的服务名称。

Docker Compose 示例：

services:

  mcp-email-server:

    image: ghcr.io/ai-zerolab/mcp-email-server:latest

    command: ["streamable-http"]

    environment:

      MCP_HOST: 0.0.0.0

      MCP_PORT: 9557

      MCP_ALLOWED_HOSTS: mcp-email-server:*,localhost:*,127.0.0.1:*

      MCP_ALLOWED_ORIGINS: http://mcp-email-server:*,http://localhost:*,http://127.0.0.1:*

像 MCP_ALLOWED_HOSTS=mcp-email-server 这样的裸主机条目也允许该主机上的任何端口。MCP_ENABLE_DNS_REBINDING_PROTECTION=false、MCP_ALLOWED_HOSTS=* 或 MCP_ALLOWED_ORIGINS=* 完全禁用 Host 和 Origin 验证。这些选项仅应在隔离的本地开发环境中使用。

允许列表中的 IPv6 文字应使用方括号表示法，例如 [::1]:* 和 http://[::1]:*。

启用附件下载

出于安全考虑，默认情况下禁用电子邮件附件下载功能。要启用此功能，您可以选择以下任一方法：

选项 1：环境变量

{

  "mcpServers": {

    "zerolib-email": {

      "command": "uvx",

      "args": ["mcp-email-server@latest", "stdio"],

      "env": {

        "MCP_EMAIL_SERVER_ENABLE_ATTACHMENT_DOWNLOAD": "true"

      }

    }

  }

}

选项 2：TOML 配置

在您的 TOML 配置文件 (~/.config/zerolib/mcp_email_server/config.toml) 中添加 enable_attachment_download = true：

enable_attachment_download = true



[[emails]]

# ... your email configuration

启用后，您可以使用 download_attachment 工具将电子邮件附件保存到指定路径。

将已发送邮件保存到 IMAP 已发送文件夹

默认情况下，已发送的邮件会自动保存到您的 IMAP 已发送文件夹中。这确保了通过 MCP 服务器发送的邮件会出现在您的邮件客户端（如 Thunderbird、webmail 等）中。

服务器会自动检测常见的已发送文件夹名称：Sent、INBOX.Sent、Sent Items、Sent Mail、[Gmail]/Sent Mail。

要指定自定义的已发送文件夹名称（适用于具有非标准文件夹名称的提供商）：

选项 1：环境变量

{

  "mcpServers": {

    "zerolib-email": {

      "command": "uvx",

      "args": ["mcp-email-server@latest", "stdio"],

      "env": {

        "MCP_EMAIL_SERVER_SENT_FOLDER_NAME": "INBOX.Sent"

      }

    }

  }

}

选项 2：TOML 配置

[[emails]]

account_name = "work"

save_to_sent = true

sent_folder_name = "INBOX.Sent"

# ... rest of your email configuration

要禁用保存到已发送文件夹，请设置 MCP_EMAIL_SERVER_SAVE_TO_SENT=false 或在您的 TOML 配置中设置 save_to_sent = false。

自签名证书和 IMAP STARTTLS（例如 ProtonMail Bridge）

像 ProtonMail Bridge 这样的本地邮件桥通常使用带有自签名证书的 STARTTLS。配置 IMAP 使用明文连接加上 STARTTLS 升级，并禁用对本地桥证书的验证：

{

  "mcpServers": {

    "zerolib-email": {

      "command": "uvx",

      "args": ["mcp-email-server@latest", "stdio"],

      "env": {

        "MCP_EMAIL_SERVER_IMAP_HOST": "127.0.0.1",

        "MCP_EMAIL_SERVER_IMAP_PORT": "1143",

        "MCP_EMAIL_SERVER_IMAP_SSL": "false",

        "MCP_EMAIL_SERVER_IMAP_START_SSL": "true",

        "MCP_EMAIL_SERVER_IMAP_VERIFY_SSL": "false",

        "MCP_EMAIL_SERVER_SMTP_VERIFY_SSL": "false"

      }

    }

  }

}

或者在 TOML 配置中：

[[emails]]

account_name = "protonmail"

# ... other settings ...



[emails.incoming]

host = "127.0.0.1"

port = 1143

use_ssl = false

start_ssl = true

verify_ssl = false



[emails.outgoing]

verify_ssl = false

对于单独的 IMAP/SMTP 凭据，您还可以使用：- MCP_EMAIL_SERVER_IMAP_USER_NAME / MCP_EMAIL_SERVER_IMAP_PASSWORD

• MCP_EMAIL_SERVER_SMTP_USER_NAME / MCP_EMAIL_SERVER_SMTP_PASSWORD

然后你可以在Claude Desktop中尝试。如果你想将其与其他mcp客户端集成，运行$which mcp-email-server以获取路径，并在你的客户端中进行如下配置：

{

  "mcpServers": {

    "zerolib-email": {

      "command": "{{ ENTRYPOINT }}",

      "args": ["stdio"]

    }

  }

}

如果docker可用，你可以尝试使用docker镜像，但你可能需要通过MCP的tools在你的客户端中进行配置。默认配置路径是~/.config/zerolib/mcp_email_server/config.toml

{

  "mcpServers": {

    "zerolib-email": {

      "command": "docker",

      "args": ["run", "-it", "ghcr.io/ai-zerolab/mcp-email-server:latest"]

    }

  }

}

通过Smithery安装

要通过Smithery自动为Claude Desktop安装Email Server：

npx -y @smithery/cli install @ai-zerolab/mcp-email-server --client claude

使用方法

回复邮件

为了正确地回复邮件（以便在电子邮件客户端中显示在同一对话中）：

1. 首先，获取原始邮件以获得其message_id：

emails = await get_emails_content(account_name="work", email_ids=["123"])

original = emails.emails[0]

1. 使用in_reply_to和references发送你的回复：

await send_email(

    account_name="work",

    recipients=[original.sender],

    subject=f"Re: {original.subject}",

    body="Thank you for your email...",

    in_reply_to=original.message_id,

    references=original.message_id,

)

in_reply_to参数设置In-Reply-To头，references设置References头。这两个头信息被电子邮件客户端用来正确地组织会话。

开发

此项目使用uv进行管理。

尝试使用make install来安装虚拟环境并安装预提交钩子。

使用uv run mcp-email-server进行本地开发。

发布新版本

• 在PyPI上创建一个API Token。
• 通过访问此页面，将API Token添加到项目的密钥中，命名为PYPI_TOKEN。
• 在Github上创建一个新发布。
• 创建一个新的标签，格式为*.*.*。

更多详情，请参见这里。