email-mcp

email-mcp

一个 Claude Code 插件,提供单一 MCP 工具 —— send_email,用于发送 Gmail 邮件,支持本地文件附件。

• OAuth 2.0,仅发送权限(gmail.send);插件无法读取你的收件箱。
• Refresh token 持久化在插件数据目录,只需授权一次。
• 附件为本地文件路径(总大小 ≤ 25 MB,Gmail 的限制)。

前置条件

• macOS / Linux / WSL
• uv 已加入 PATH

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

  macOS 用户额外一步:Claude Code Desktop 从 Finder/Dock 启动时不读 shell rc,看不到 ~/.local/bin。需要把 uv 软链到系统路径:

  sudo ln -s "$HOME/.local/bin/uv" /usr/local/bin/uv
  

• 一个用于发件的 Google 账号

1. 获取 OAuth 客户端密钥

1. 打开 https://console.cloud.google.com/,创建(或选择)一个项目。
2. APIs & Services → Library → Gmail API → 启用。
3. Google Auth Platform → Branding —— 按向导填写,User type 选 External。在 Audience → Test users 中加入你的 Gmail 邮箱。
4. Google Auth Platform → Clients → + Create Client。Application type 选 Desktop app,下载 JSON。

把文件保存到稳定位置(例如 ~/.config/email-mcp/credentials.json)。安装插件时需要填这个路径。

2. 安装插件

方式 A —— 本地目录(当前用法)

# 在 Claude Code 会话中
/plugin marketplace add /Users/yuanyuexiang/Desktop/workspace/email-mcp
/plugin install email-mcp@email-mcp

弹出安装对话框时,在 credentials.json path 字段填入第 1 步保存的路径。

方式 B —— 从 GitHub 安装(发布之后)

/plugin marketplace add <github-user>/email-mcp
/plugin install email-mcp@email-mcp

3. 授权 Gmail(一次性)

💡 如果 /email-mcp:authorize 报"找不到 email-mcp"或"venv 不存在"之类的错,说明 SessionStart 钩子还没跑完依赖安装。重启 Claude Code Desktop 一次让钩子完整执行,再回来执行授权。

在 Claude Code 中运行:

/email-mcp:authorize

浏览器会打开一个标签页。用你想发件的 Gmail 账号登录,接受 "Google hasn't verified this app" 提示(你的账号已在 Test users 名单里),并授予 gmail.send 权限。插件会把 token.json 写入数据目录,之后无需再管。

4. 发送邮件

执行 /mcp (重新)加载 MCP server,然后向 Claude 提问即可:

给 [email protected] 发一封邮件,主题 "周报",正文 "见附件",附件 /path/to/report.pdf

Claude 会调用 send_email MCP 工具。

send_email 工具参数说明

参数	类型	必填	说明
to	list[str]	是	一个或多个收件人
subject	str	是
body	str	是	纯文本正文
cc	list[str]	否
bcc	list[str]	否
body_html	str	否	HTML 格式备用正文
attachments	list[str]	否	本地文件路径,总大小 ≤ 25 MB

返回 {"id", "threadId", "to"}。

文件位置一览

用途	路径
插件源码(缓存)	~/.claude/plugins/cache/email-mcp-<...>/
Python 虚拟环境(持久)	~/.claude/plugins/data/email-mcp-<...>/.venv
OAuth refresh token	~/.claude/plugins/data/email-mcp-<...>/token.json
OAuth 客户端密钥	你自己保存 credentials.json 的位置

卸载插件默认会清除数据目录(加 --keep-data 可保留)。

故障排查

现象	解决方法
会话启动时报 uv: command not found	macOS GUI 启动看不到 ~/.local/bin;按前置条件做 uv 软链,然后重启 Claude Code
MCP 工具报 No valid Gmail credentials	重新执行 /email-mcp:authorize
大约 7 天后突然 No valid Gmail credentials	Google 对 Testing 模式应用的 refresh token 强制 7 天过期。重新执行 /email-mcp:authorize 即可;要彻底解决,需把 OAuth 应用提交为 Published 状态
浏览器显示 Error 403: access_denied	在 Auth Platform 的 Audience → Test users 里加上你的 Gmail
想切换授权到另一个账号	删掉数据目录里的 token.json,重新执行 /email-mcp:authorize

开发

脱离插件 harness 单独运行 server:

cd /Users/yuanyuexiang/Desktop/workspace/email-mcp
uv sync
GMAIL_CREDENTIALS_PATH=~/.config/email-mcp/credentials.json \
GMAIL_TOKEN_PATH=~/.config/email-mcp/token.json \
uv run email-mcp auth   # 仅需一次
uv run email-mcp        # 启动 stdio MCP server

通过 GMAIL_CREDENTIALS_PATH 和 GMAIL_TOKEN_PATH 可在任何环境下覆盖默认路径。