使用说明

email-mcp

一个基于 Go 的邮箱 MCP 服务，当前第一版优先打通 Gmail，并保留多账号、HTTP 和 stdio 双入口能力。

架构

实现架构说明见：

当前能力

多账号配置存储
Gmail / Outlook / 163 / QQ provider preset
IMAP 连接测试
SMTP 连接测试
列出邮箱目录
搜索邮件
读取邮件正文
发送支持 To / Cc / Bcc / Reply-To 的邮件
MCP stdio 模式
MCP Streamable HTTP 模式

启动方式

1. stdio

go run ./cmd/email-mcp serve-stdio

2. HTTP

go run ./cmd/email-mcp serve-http --addr :8080 --public-base-url http://localhost:8080

默认端口说明：

MCP HTTP 入口：POST /mcp
Google OAuth 启动入口：GET /oauth/google/start?account_id=...
Google OAuth 回调入口：GET /oauth/google/callback
健康检查：GET /healthz

3. 初始化 Gmail OAuth 账号

go run ./cmd/email-mcp init-gmail-oauth \
  --email your-name@gmail.com \
  --client-id your-google-client-id \
  --client-secret your-google-client-secret

这个命令会把一个 auth_type=oauth2 的 Gmail 账号写入账号配置文件。

4. 本地调试命令

测试账号连通性：

go run ./cmd/email-mcp test-account --account-id gmail-main

列出邮箱目录：

go run ./cmd/email-mcp list-mailboxes --account-id gmail-main

搜索最近邮件：

go run ./cmd/email-mcp search-messages --account-id gmail-main --mailbox INBOX --limit 20

如果你不想使用默认账号文件路径，可以为任意命令附带：

--accounts-file /path/to/accounts.json

accounts.json 配置

默认账号配置文件路径：

~/.email-mcp/accounts.json

也可以通过环境变量覆盖：

export EMAIL_MCP_ACCOUNTS_FILE=/path/to/accounts.json

当前程序启动时会做一次兼容迁移：

如果 ~/.email-mcp/accounts.json 不存在
但项目里的旧文件 data/accounts.json 存在
启动时会自动迁移到用户目录

accounts.json 顶层结构

accounts.json 顶层是一个数组，每个元素代表一个邮箱账号。

[
  {
    "...": "一个邮箱账号对象"
  }
]

通用字段说明

每个账号对象包含这些常见字段：

id
- 账号唯一标识，MCP 调用时通过它指定账号
provider
- 例如 gmail、outlook、163、qq
email_address
- 邮箱地址
display_name
- 发件显示名
imap
- IMAP 连接配置
smtp
- SMTP 连接配置
auth
- 认证配置
enabled
- 是否启用
is_default
- 是否默认账号
created_at
updated_at

App Password 示例

这是 Gmail 最容易先跑通的配置方式：

[
  {
    "id": "gmail-main",
    "provider": "gmail",
    "email_address": "your-name@gmail.com",
    "display_name": "Your Name",
    "imap": {
      "host": "imap.gmail.com",
      "port": 993,
      "security": "tls",
      "username": "your-name@gmail.com"
    },
    "smtp": {
      "host": "smtp.gmail.com",
      "port": 465,
      "security": "tls",
      "username": "your-name@gmail.com"
    },
    "auth": {
      "type": "app_password",
      "password": "your-16-char-app-password"
    },
    "enabled": true,
    "is_default": true,
    "created_at": "2026-03-18T00:00:00Z",
    "updated_at": "2026-03-18T00:00:00Z"
  }
]

Google OAuth 示例

如果你要走 Google OAuth，初始配置可以这样：

[
  {
    "id": "gmail-oauth",
    "provider": "gmail",
    "email_address": "your-name@gmail.com",
    "display_name": "Your Name",
    "imap": {
      "host": "imap.gmail.com",
      "port": 993,
      "security": "tls",
      "username": "your-name@gmail.com"
    },
    "smtp": {
      "host": "smtp.gmail.com",
      "port": 465,
      "security": "tls",
      "username": "your-name@gmail.com"
    },
    "auth": {
      "type": "oauth2",
      "oauth2": {
        "provider": "google",
        "client_id": "your-google-client-id",
        "client_secret": "your-google-client-secret",
        "scopes": [
          "https://mail.google.com/"
        ]
      }
    },
    "enabled": true,
    "is_default": true,
    "created_at": "2026-03-18T00:00:00Z",
    "updated_at": "2026-03-18T00:00:00Z"
  }
]

Google OAuth 授权成功后，程序会自动把这些字段回写进去：

auth.oauth2.refresh_token
auth.oauth2.access_token
auth.oauth2.token_expiry

Gmail 接入建议

方案 A：App Password

建议先准备一个 Gmail App Password，然后用 email.account.create 创建账号：

{
  "id": "gmail-main",
  "provider": "gmail",
  "email_address": "your-name@gmail.com",
  "display_name": "Your Name",
  "auth_type": "app_password",
  "password": "your-app-password"
}

然后依次调用：

email.account.test_connection
email.mailbox.list
email.message.send

Gmail 认证注意：

App Password 的前置条件是开启 2-Step Verification（两步验证）
- 如何检查是否已开启：
  1. 打开 Google 账号安全页：https://myaccount.google.com/security
  2. 找到 “How you sign in to Google / 登录 Google 的方式” 或 “Signing in to Google / 登录 Google”
  3. 查看 “2-Step Verification / 两步验证” 是否为 “On / 已开启”
- 如何开启（未开启时）：
  1. 进入 https://myaccount.google.com/security
  2. 选择 “2-Step Verification / 两步验证” 并按引导完成（常见方式：Google Prompt、Authenticator、短信等）
获取 App Password（应用专用密码）：
1. 确认两步验证已开启后，打开：https://myaccount.google.com/apppasswords
2. 在 “Select app / 选择应用” 里选 “Mail / 邮件”（或选 “Other / 其他” 自定义一个名字）
3. 在 “Select device / 选择设备” 随便选一个（只影响显示名，不影响实际可用性）
4. 点击 “Generate / 生成”，复制得到的 16 位 App Password
5. 把这 16 位字符串作为上面 password 字段的值（不需要再输入 Google 账号密码）
Google Workspace（公司/学校域名账号）注意：
- Workspace 官方帮助页提到，自 2025 年 5 月 1 日起，Workspace 账号不再支持只用账号密码给第三方应用登录
- 另外，部分 Workspace 组织会在管理员侧禁用 App Password 或强制更严格的登录策略；若你在 https://myaccount.google.com/apppasswords 看不到入口或无法生成，优先走 OAuth2（见下方“方案 B”）

方案 B：OAuth2

现在已经支持完整的 Google OAuth 浏览器授权。当前实现方式是：

你在 Google Cloud Console 创建 OAuth Client
先创建一个 auth_type=oauth2 的 Gmail 账号配置
打开 /oauth/google/start?account_id=...
浏览器完成 Google 授权后，服务端自动保存 refresh_token
服务端运行时自动换取 access_token
IMAP / SMTP 使用 XOAUTH2 登录 Gmail

OAuth2 账号示例：

{
  "id": "gmail-oauth",
  "provider": "gmail",
  "email_address": "your-name@gmail.com",
  "display_name": "Your Name",
  "auth_type": "oauth2",
  "oauth2": {
    "provider": "google",
    "client_id": "your-google-client-id",
    "client_secret": "your-google-client-secret",
    "scopes": [
      "https://mail.google.com/"
    ]
  }
}

然后访问：

http://localhost:8080/oauth/google/start?account_id=gmail-oauth

Google 回调成功后，账号文件里会自动写入：

refresh_token
access_token
token_expiry

最短跑通步骤

在 Google Cloud Console 创建 OAuth Client
在 Google OAuth consent screen 里把自己加入测试用户
把回调地址加入 Authorized redirect URIs：
- http://localhost:8080/oauth/google/callback
运行初始化命令：

go run ./cmd/email-mcp init-gmail-oauth \
  --email your-name@gmail.com \
  --client-id your-google-client-id \
  --client-secret your-google-client-secret

启动 HTTP 服务：

go run ./cmd/email-mcp serve-http --addr :8080 --public-base-url http://localhost:8080

浏览器打开：

http://localhost:8080/oauth/google/start?account_id=gmail-oauth

授权成功后，再测试：

email.account.test_connection
email.mailbox.list
email.message.send

Gmail OAuth 所需字段

client_id
client_secret

当前限制

账号凭证当前以本地 JSON 文件存储，适合开发阶段，不适合直接生产落地
当前 Google OAuth 只实现了 Gmail
stdio 模式本身不能直接承载浏览器回调，所以第一次授权要通过 HTTP 模式完成
还没有实现附件发送、回复、转发