AI导哈

邮件协议服务器

一个用于电子邮件操作（支持POP3/SMTP与TLS）的模型上下文协议（MCP）服务器，允许像Claude这样的LLM读取、发送和管理电子邮件。

  • by ptbsare
  • Python
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 ptbsare/mcp_email_server

使用说明

MCP电子邮件服务器

用于电子邮件操作的模型上下文协议（MCP）服务器（带TLS的POP3/SMTP）。允许像Claude这样的LLM阅读、发送和管理电子邮件。

快速开始

选项1:uvx（推荐）

无克隆，无安装——直接从GitHub运行：

uvx git+https://github.com/ptbsare/email-mcp-server \
  --email-user you@example.com \
  --email-pass yourpassword \
  --pop3-server pop.example.com \
  --smtp-server smtp.example.com

第一次运行会缓存包；随后的发射是即时的。

选项2：克隆+本地运行

git clone https://github.com/ptbsare/email-mcp-server
cd email-mcp-server
uv pip install -e .
uv run main.py --email-user you@example.com --email-pass yourpassword \
  --pop3-server pop.example.com --smtp-server smtp.example.com

选项3:.env文件

创建一个 .env 工作目录中的文件：

EMAIL_USER=you@example.com
EMAIL_PASS=yourpassword
POP3_SERVER=pop.example.com
SMTP_SERVER=smtp.example.com

然后简单地说：

uvx git+https://github.com/ptbsare/email-mcp-server
# or
uv run main.py

配置

配置优先级（最高→ 最低）

  1. CLI参数 --覆盖所有内容
  2. 环境变量 以（权力）否决 .env 文件
  3. .env 文件 --回退默认值

所有配置选项

CLI参数 环境变量 必需 默认值 描述
--email-user EMAIL_USER ✅ — 电子邮件地址
--email-pass EMAIL_PASS ✅ — 电子邮件密码/应用程序密码
--pop3-server POP3_SERVER ✅ — POP3服务器主机名
--pop3-port POP3_PORT 995 POP3 SSL端口
--smtp-server SMTP_SERVER ✅ — SMTP服务器主机名
--smtp-port SMTP_PORT 587 SMTP端口（自动 465 如果 --smtp-use-ssl)
--smtp-use-ssl SMTP_USE_SSL false 使用SMTP_SSL（端口465）而不是STARTTLS
--log-level LOG_LEVEL INFO 日志记录： DEBUG / INFO / WARNING / ERROR

示例：混合配置源

# CLI args only (no .env needed):
uv run main.py --email-user me@gmail.com --email-pass xxx \
  --pop3-server pop.gmail.com --smtp-server smtp.gmail.com

# .env file for credentials, CLI for servers:
# .env: EMAIL_USER=me@gmail.com / EMAIL_PASS=xxx
uv run main.py --pop3-server pop.gmail.com --smtp-server smtp.gmail.com

# Env vars override .env:
EMAIL_USER=other@gmail.com uv run main.py --pop3-server pop.gmail.com ...

与Claude Desktop一起使用

添加到您的Claude Desktop配置文件中：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json 窗户： %APPDATA%/Claude/claude_desktop_config.json

使用env变量（在配置中）：

{
  "mcpServers": {
    "email-mcp-server": {
      "command": "uvx",
      "args": ["git+https://github.com/ptbsare/email-mcp-server"],
      "env": {
        "EMAIL_USER": "your-email@example.com",
        "EMAIL_PASS": "your-app-password",
        "POP3_SERVER": "pop.example.com",
        "SMTP_SERVER": "smtp.example.com"
      }
    }
  }
}

使用CLI参数（在配置中）：

{
  "mcpServers": {
    "email-mcp-server": {
      "command": "uvx",
      "args": [
        "git+https://github.com/ptbsare/email-mcp-server",
        "--email-user", "your-email@example.com",
        "--email-pass", "your-app-password",
        "--pop3-server", "pop.example.com",
        "--smtp-server", "smtp.example.com"
      ]
    }
  }
}

提示： 这 env section和CLI参数可以一起使用。CLI参数始终具有优先级。

特征

  • 投票电子邮件： 列出具有可配置限制的收件箱电子邮件标题(pollEmails)
  • 获取完整电子邮件： 通过ID获取完整的电子邮件内容，并自动提取附件(getEmailsById)
  • 删除电子邮件： 按ID删除电子邮件(deleteEmailsById)
  • 发送电子邮件： 发送纯文本(sendTextEmail)或HTML(sendHtmlEmail)带有可选文件附件的电子邮件
  • 安全连接： SSL上的POP3（端口995）、带STARTTLS的SMTP（端口587）或直接SSL（端口465）
  • 附件支持： 将本地文件作为附件发送；收到的附件会自动保存到 /tmp/email_mcp_attachments/<email_id>/

工具

pollEmails(limit=50)

列出最近的电子邮件标题（无正文）。先返回最新的。首先使用此方法获取ID getEmailsById/deleteEmailsById.

参数 类型 默认值 说明
limit int 50 最多可返回的电子邮件，最新邮件优先

退货： [{"id": int, "Subject": str, "From": str, "Date": str, "Message-ID": str}]

pollEmails(limit=10)   # 10 most recent
pollEmails()           # default 50

getEmailsById(ids)

按ID从以下位置获取完整的电子邮件内容（页眉+正文） pollEmails.附件自动保存到 /tmp/email_mcp_attachments/<id>/.

参数 类型 必填 说明
ids list[int] ✅ 来自的电子邮件ID pollEmails()示例： [1, 3, 5]

退货： [{"id": int, "headers": dict, "body": str, "attachments": [{"filename": str, "local_path": str, "size": int, "content_type": str}]}]

getEmailsById(ids=[1, 3, 5])

deleteEmailsById(ids)

按ID永久删除电子邮件。 不可逆转。 呼叫 pollEmails 第一。

参数 类型 必填 说明
ids list[int] ✅ 来自的电子邮件ID pollEmails()示例： [1, 2, 3]

退货： {"deleted": [int], "failed": {"id": "error msg"}}

deleteEmailsById(ids=[1, 2, 3])

sendTextEmail(toAddresses, subject, body, attachments=None)

发送一封纯文本电子邮件。附件：本地文件路径列表，如 ["/tmp/file.pdf"].

参数 类型 必填 默认 说明
toAddresses list[str] ✅ — 收件人。例子： ["alice@example.com"]
subject str ✅ — 主题行
body str ✅ — 纯文本正文
attachments list[str] None 本地文件路径。例子： ["/tmp/report.pdf"]

退货： {"status": "success"}

sendTextEmail(
    toAddresses=["alice@example.com"],
    subject="Hello",
    body="Hi Alice!",
    attachments=["/tmp/report.pdf"]
)

sendHtmlEmail(toAddresses, subject, body, attachments=None)

发送一封HTML电子邮件。附件：本地文件路径列表，如 ["/tmp/file.png"].

参数 类型 必填 默认 说明
toAddresses list[str] ✅ — 收件人。例子： ["alice@example.com"]
subject str ✅ — 主题行
body str ✅ — HTML内容。例子： "<h1>Hi</h1><p>Hello!</p>"
attachments list[str] None 本地文件路径。例子： ["/tmp/chart.png"]

退货： {"status": "success"}

sendHtmlEmail(
    toAddresses=["alice@example.com"],
    subject="Report",
    body="<h1>Report</h1><p>Sales up <b>20%</b>.</p>",
    attachments=["/tmp/chart.png"]
)

开发设置

先决条件

步骤

git clone https://github.com/ptbsare/email-mcp-server
cd email-mcp-server
uv pip install -e .
uv run main.py --help

重要提示

  • 应用程序密码： 如果您的电子邮件提供商使用2FA，请为生成应用程序密码 EMAIL_PASS
  • 电子邮件ID: POP3 ID是特定于会话的。呼叫 pollEmails() 之前 getEmailsById() 或 deleteEmailsById()
  • 附件存储： 收到的附件将保存到 /tmp/email_mcp_attachments/<email_id>/
  • 安全： 永远不要承诺你的 .env 文件--它已经在 .gitignore
  • 配置优先级： CLI参数>环境变量> .env 文件

项目结构

email-mcp-server/
├── main.py              # MCP server entry point (all logic)
├── pyproject.toml       # Package config & dependencies
├── uv.lock              # Dependency lock file
├── .env                 # Credentials (create your own)
├── .gitignore
└── README.md

许可证

麻省理工学院

相关 MCP