productivity-mcp

本地 Model Context Protocol 服务器，为 LLM 客户端（Claude Desktop、Kiro 或任何支持 MCP 的应用）提供对您的 电子邮件和日历 的读/写访问权限。

支持：

完全在您的机器上通过 stdio 运行。除了发送到您配置的邮件/日历服务器外，没有任何数据会离开您的计算机。

安装

需要安装了 Homebrew 的 macOS。其他所有依赖（Python 3.13, uv, git）均按需安装。

git clone https://github.com/seandkendall/productivity-mcp.git
cd productivity-mcp
./setup.sh

./setup.sh 会通过 brew 安装任何缺失的先决条件，创建虚拟环境，安装软件包，并启动交互式配置向导。

Related MCP server: multi-mail-mcp

配置

运行交互式向导 — 它会创建一个 venv，安装软件包，然后询问您的凭据并为您写入配置：

./setup.sh

该向导支持：

• iCloud / Apple Mail — 输入您的电子邮件 + 应用专用密码即可。同时设置邮件和日历。

• Gmail / Google Calendar — 指向您的 OAuth 客户端 JSON（请参阅下文了解如何获取）。

• 通用 IMAP — 选择预设（Fastmail, Yahoo, Outlook）或输入自定义主机/端口。

配置将以 0600 权限写入 ~/.config/productivity-mcp/config.toml。您可以随时重新运行向导来添加或替换账户。

Gmail：一次性 Google Cloud 设置

Google 已于 2025 年 3 月禁用了 IMAP/SMTP 应用专用密码，因此 Gmail 需要 OAuth2。在运行向导之前：

1. 打开 Google Cloud Console → 创建或选择一个项目。

2. APIs & Services → Library → 启用 Gmail API 和 Google Calendar API。

3. APIs & Services → OAuth consent screen → 设置为 External（将您自己添加为测试用户）。

4. Credentials → Create credentials → OAuth client ID → Desktop app → 下载 JSON。

然后运行 productivity-mcp setup，选择 Gmail，并指向下载的 JSON。首次工具调用会打开浏览器进行授权；刷新令牌将在本地缓存。

iCloud：一次性 Apple ID 设置

登录 appleid.apple.com → Sign-In and Security → App-Specific Passwords → 生成一个。在向导提示时将其粘贴进去。

手动配置（可选）

如果您更喜欢直接编辑 TOML，请将 example.config.toml 复制到 ~/.config/productivity-mcp/config.toml。

运行

productivity-mcp

这通过 stdio 运行 — 您将其连接到客户端，而不是作为长期运行的守护进程运行。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
 "mcpServers": {
 "productivity": {
 "command": "/absolute/path/to/.venv/bin/productivity-mcp"
 }
 }
}

重启 Claude Desktop。工具将出现在 🔌 菜单下。

Kiro

在 Kiro 设置中，添加一个命令为 productivity-mcp（或 venv 二进制文件的绝对路径）的 MCP 服务器。它将通过 stdio 运行。

可用工具 (39)

如果任何工具省略了 account，则使用该类型的第一个已配置账户。请参阅 list_email_accounts / list_calendar_accounts 以查找名称和别名。

电子邮件 — 读取与发现

• list_email_accounts — 已配置的账户及其 addresses（主地址 + 别名）

• list_folders(account?) — IMAP 文件夹 / Gmail 标签

• list_emails(account?, folder="INBOX", limit=25, query?, unread_only=false, recipients?, since_days?, senders?)

• read_email(message_id, account?, folder="INBOX", format="text"|"html"|"both") — HTML 正文默认渲染为纯文本

• search_threads(account?, folder="INBOX", query?, senders?, recipients?, since_days?, limit=25) — 按对话去重

• search_emails_by_sender(senders, account?, folder="INBOX", since_days?, limit=25)

• count_emails(account?, folder="INBOX", query?, unread_only=false, senders?, recipients?, since_days?)

• count_unread(account?, folder="INBOX", since_days?)

• list_recent_senders(account?, folder="INBOX", since_days=30, top=20)

• summarize_inbox(account?, folder="INBOX", since_days=7, top=10) — 总计、热门发件人、热门域名、热门收件人别名、每日直方图

• resolve_contact(query, account?, limit=10) — 姓名/电子邮件查找（Gmail People API 或最近消息扫描）

电子邮件 — 写入（速率限制）

• send_email(to, subject, body, account?, cc?, bcc?, html=false)

• reply_email(message_id, body, reply_all=false, account?, folder="INBOX", html=false)

• forward_email(message_id, to, body="", account?, folder="INBOX", html=false)

• set_email_read(message_id, read=true, account?, folder="INBOX")

• delete_email(message_id, account?, folder="INBOX")

• move_email(message_id, target_folder, account?, folder="INBOX")

• bulk_set_read(message_ids, read=true, account?, folder="INBOX")

• bulk_delete_emails(message_ids, account?, folder="INBOX")

• bulk_move_emails(message_ids, target_folder, account?, folder="INBOX")

电子邮件 — 草稿与附件

• save_draft(to, subject, body, account?, cc?, bcc?, html=false)

• list_drafts(account?, limit=25)

• send_draft(draft_id, account?)

• list_attachments(message_id, account?, folder="INBOX")

• download_attachment(message_id, attachment_id, save_to?, account?, folder="INBOX") — 保存到磁盘或返回 base64

日历

• list_calendar_accounts

• list_calendars(account?)

• list_events(account?, calendar?, start?, end?, limit=100) — 默认为未来 7 天

• get_event(event_id, account?, calendar?)

• search_events(query, account?, calendar?, start?, end?, limit=50)

• create_event(summary, start, end, account?, calendar?, description?, location?, attendees?)

• update_event(event_id, account?, calendar?, summary?, start?, end?, description?, location?, attendees?)

• delete_event(event_id, account?, calendar?)

• respond_event(event_id, response, account?, calendar?) — accept | decline | tentative

• free_busy(start, end, account?, attendees?) — 原生 Google freebusy.query；EWS/CalDAV 回退到事件枚举

• suggest_meeting_times(duration_minutes, window_start, window_end, account?, attendees?, working_hours_start=9, working_hours_end=17, limit=5)

任务

• list_tasks(account?, limit=50) — Google Tasks (Google Calendar 账户) 或 EWS Tasks (WorkMail)

• create_task(title, account?, due?, notes?)

诊断

• ping(account?) — 探测每个已配置的账户；返回每个账户的 {ok, latency_ms, error?}

可观测性

每次工具调用都会向 stderr 发出结构化 JSON：

{"ts":"...","level":"INFO","msg":"tool_call.start","tool":"list_emails","call_id":"b69185a6","arg_keys":["limit"]}
{"ts":"...","level":"INFO","msg":"tool_call.end","tool":"list_emails","call_id":"b69185a6","duration_ms":420}

仅记录参数 键 — 值永远不会泄露。调试时将 stderr 重定向到文件。

速率限制

破坏性工具具有软速率限制，以防止意外的 LLM 循环。默认值（每个服务器进程，滑动窗口）：

超过限制时，工具会返回带有重试延迟的 RuntimeError。重启服务器以重置。

开发

# Lint
ruff check src tests
ruff format src tests

# Tests
pytest

安全

• 密钥存储在 ~/.config/productivity-mcp/config.toml 中 — 绝不提交，绝不传输到除您配置的邮件/日历服务器之外的任何地方。

• Gmail OAuth 令牌缓存在您指定的 token_file 路径中；请像对待密码一样对待它们。

• 对于 iCloud/IMAP，请务必使用 应用专用密码，切勿使用您的主账户密码。

许可证

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• bulk_delete_emailsA
• bulk_move_emailsC
• bulk_set_readA
• count_emailsA
• count_unreadB
• create_eventC
• create_taskC
• delete_emailA