内容
# @indianic/mailman
[](https://www.npmjs.com/package/@integratex/mailman)
[](https://opensource.org/licenses/MIT)
[](https://nodejs.org)
邮件管理器 CLI — 通过询问 AI 助手发送和阅读 Gmail，专为印度尼克基础设施构建。
> 🌐 **实时演示和文档：** [mailman.indianic.dev](https://mailman.indianic.dev)
> 📦 **公共构建：** [`@integratex/mailman`](https://www.npmjs.com/package/@integratex/mailman) — `npm i -g @integratex/mailman`
## 看看它的实际操作
用简单的英语询问你的 AI。邮件管理器 **草拟，预览，只有在你确认后才发送** — 绝不会在你询问的瞬间发送。
**真实的提示，适用于 Claude Code · Cursor · Gemini CLI · Windsurf** — 电子邮件发生在你已经工作的任何地方:
## 功能
- 从 AI 助手用简单的英语 **发送和阅读** Gmail — “发送那些文档给 Kalpesh”，“显示我最近 10 封邮件”
- **草拟 → 预览 → 确认** 安全 — 除非你批准，否则不会发送（`confirm_send` 不会在没有明确确认的情况下分发）
- **182 个消息模板** + `list_templates` （FYI，跟进，会议，转发/回复等 — 主题前缀 + 你的 AI 助手撰写的提示）
- 附件（文件，文件夹，`*.pdf` 通配符），**定时发送** 通过 OS 计时器，收件箱列表 / 读取 / 搜索，联系人 + 收件人建议
- 多账户，机器绑定加密凭证（OS 密钥链），发送桌面通知
- 安装到 **Claude Code，Cursor，Gemini CLI，Windsurf，Codex** (`mailman register`) — 跨平台 Win/Mac/Linux
- 23 个 MCP 工具，通过 MCP 公开给你的 AI
## 安装
将 `@indianic` 范围指向私有注册表，然后使用 **npm** 或 **pnpm** 全局安装：
```bash
# npm
npm config set @indianic:registry https://npm.indianic.in
npm install -g @indianic/mailman
# pnpm
pnpm config set @indianic:registry https://npm.indianic.in
pnpm add -g @indianic/mailman
```
（范围配置存储在 `~/.npmrc` 中 — npm，pnpm 和 yarn 都读取它 — 因此不需要 `--registry` 标志，并且公共依赖仍然从公共注册表解析。`mailman update` 稍后使用您使用的包管理器原地升级。）
## 用法
```bash
# 首次设置 — 添加 Gmail 账户（电子邮件 + 应用密码）和
# 注册你的 AI 工具（Claude Code，Cursor，Gemini CLI，Windsurf，Codex）
mailman init
# 稍后注册 AI 编辑器
mailman register --tools claude,cursor
mailman register -i
# 诊断和当前状态
mailman doctor
mailman status
# 账户，联系人，设置
mailman account add
mailman settings set defaultBodyType html
mailman settings set desktopNotifications false
# 定时发送
mailman scheduled list
# 自我更新
mailman update
# 帮助和版本
mailman help
mailman --version
```
安装并注册后，您与 AI 助手交谈 — 而不是 CLI — 进行日常电子邮件：
```bash
你：mailman，发送那些文档给 kalpesh.gamit@indianic.com
AI： [草拟主题/正文，解析附件] 准备发送 — 确认？
你：是的
AI： 已发送。
你：mailman，列出我最近 10 封邮件
你：搜索上个月的发票
你：改为明天 9 点发送，而不是现在 # 即使工具关闭，也会发送
```
> **软件包与命令名称。** npm 软件包是 **`@indianic/mailman`**；它安装一个 CLI，您可以作为 **`mailman`** 运行。第二个别名 **`mcp-mailman`** 指向同一个二进制文件 — 仅在同时具有 GNU Mailman 的 `/usr/bin/mailman` 的主机上使用它。
## 工作原理
一个原生 stdio **MCP 服务器**：您的编辑器通过 `npx -y @indianic/mailman` 启动它，Claude 调用其工具的自然语言。它通过两种方式访问 Gmail — **SMTP/IMAP** 用于应用密码帐户，或 **Gmail REST API** 用于 OAuth2 帐户。纯 Node.js，因此行为在 macOS、Linux 和 Windows 上相同。配置一次，全球可用 — 可从任何项目访问。
手动 MCP 配置（`init`/`register` 为您编写 — 注意它 **不包含秘密**，凭证存储在 OS 密钥链中）：
```json
{
"mcpServers": {
"mailman": { "command": "npx", "args": ["-y", "@indianic/mailman"] }
}
}
```
- **Claude Code** — `claude mcp add mailman -- npx -y @indianic/mailman`
- **Cursor / Windsurf / Gemini CLI / Codex** — 将块添加到该工具的 MCP 配置文件中。
## 文档
- [docs/FEATURES.md](docs/FEATURES.md) — 普通英语 + 技术功能游览
- [docs/PLAN.md](docs/PLAN.md) — 架构：身份验证，存储，工具，流程
- [docs/SKILLS.md](docs/SKILLS.md) — MCP 工具服务器公开的工具
- [docs/CLI.md](docs/CLI.md) — 每个终端命令（设置，帐户，诊断）
- [docs/CROSS-OS.md](docs/CROSS-OS.md) — 每个 OS 的支持矩阵
## OAuth2 / 浏览器登录（无密码路径）
常规 Gmail 密码 **不能** 与 mailman 一起使用 — Google 在 2022 年禁用了 SMTP/IMAP 的密码登录，因此只接受 **应用密码** 或 **OAuth2**。`mailman init` / `account add` 打开时有选择：**应用密码** （粘贴 16 个字符的代码 — 默认，最简单的路径）或 **使用浏览器登录（OAuth2）** — 无密码，并且如果您是无密码/无密码或您的 Workspace 管理员禁用应用密码，则可以选择此选项。`mailman auth login <alias>` 与独立命令相同，是相同的 OAuth2 流。
通行密钥不能直接交给 SMTP/IMAP，但它们在 **浏览器登录** 时有效：当 OAuth2 打开 Google 的同意页面时，请在那里使用通行密钥进行身份验证 — mailman 存储生成的刷新令牌，而不是通行密钥。
OAuth2 使用 **您自己的** Google Cloud OAuth 客户端 — 一次性设置，替换每个帐户的密码。浏览器打开以获取同意，并存储加密的刷新令牌。在无头框上，它打印同意 URL 和 `ssh -L` 隧道命令，而不是启动浏览器。
### 创建 OAuth 客户端（一次性，~2 分钟）
1. **Google Cloud Console** → 创建/选择项目 → **APIs & Services → Library** → 启用 **Gmail API** （和 **People API** 如果您想要联系人建议）。
2. **APIs & Services → OAuth 同意屏幕** → **外部** → 添加您自己作为 **测试用户** （这样您不需要 Google 应用验证）。发布状态可以保持“测试中”。
3. **APIs & Services → Credentials → Create credentials → OAuth 客户端 ID** → **应用程序类型：`Desktop app`**。 ⚠️ **这必须是 `Desktop app`**，而不是 `Web application`。
4. 复制 **客户端 ID** 和 **客户端密钥** — 粘贴它们，当 `auth login` / `account add` 询问。
> **`Error 400: redirect_uri_mismatch`?** 您的客户端是 **Web 应用程序** 类型。 mailman 通过循环重定向登录 (`http://127.0.0.1:<random-port>`)，这 **只有 Desktop-app 客户端允许** — Web 应用程序客户端需要每个重定向 URI 都预先注册为固定端口，因此随机端口始终失败。删除客户端并创建一个 **Desktop app** 客户端。
请求的范围：`gmail.send`，`gmail.readonly`，`contacts.readonly`。（`gmail.readonly` 是对整个邮箱的读取访问 — 应用密码帐户通过 IMAP 隐含等效读取访问。）
## 安全
凭证 **机器绑定**，不仅加密：加密密钥存储在您的 OS 原生存储（macOS 密钥链，Windows 凭证管理器，Linux 秘密服务通过 `keytar`）中，而不是在配置文件目录中。复制 `accounts.json` 到另一台机器会产生无用的密文 — `mailman` 拒绝解密而不是降级。每个工具调用都会追加到本地 `activity.log`（工具名称 + 非敏感元数据 — 绝不会是正文/凭证）。
> Linux 无头需要运行的秘密服务提供程序（gnome-keyring，kwallet）。没有密钥环 → 设置失败，并有说明而不是存储明文。请参阅 [docs/CROSS-OS.md](docs/CROSS-OS.md)。
## 配置位置
所有状态（帐户，联系人/最近，设置）都存储在一个全局的，每个 OS 用户的目录中 — 从不在项目中：
| OS | 路径 |
|---|---|
| macOS | `~/Library/Application Support/mcp-mailman/` |
| Linux | `~/.config/mcp-mailman/` |
| Windows | `%APPDATA%\mcp-mailman\` |
## 桌面通知
每次成功发送（交互式 **和** 定时），mailman 都会触发一个原生桌面通知 — macOS 通知中心 (`osascript`)，Linux `notify-send`，Windows toast。**默认启用**；尽力而为（绝不会阻止/失败发送）。切换：
```bash
mailman settings set desktopNotifications false
mailman settings set desktopNotifications true
```
## 保持更新
交互式 `mailman` 命令显示一个一行“可用更新”通知，当发布新版本时（每天缓存）。升级就地 — 它使用安装它的包管理器（npm 或 pnpm）：
```bash
mailman update # 或：mailman upgrade
```
在重启 AI 工具后，其 MCP 服务器会获取新版本。
## 许可证
MIT
