内容
# Fluxmail
Fluxmail 是一个自主托管的 MCP 服务器，它将 AI 代理连接到您的电子邮件。它通过 Gmail API 与 Gmail 通信；Outlook（Microsoft Graph）和 IMAP 适配器正在开发中。代理获得一组工具来读取、搜索、草拟、发送和组织邮件，并且这些工具在添加更多提供商时保持不变。
- 14 个 MCP 工具，通过 stdio（Claude Desktop，Claude Code）或可流式传输的 HTTP（Docker，远程部署）提供
- 一个与提供商无关的模型（文件夹、线程、草稿、结构化查询语言），因此在提供商层之上没有任何内容知道它正在与 Gmail 通信
- 一个带有 SQLite 存储的 Docker 容器；OAuth 令牌在静止时使用 AES-256-GCM 进行加密
- 个人计划上免费托管（3 个邮箱，1 个成员）；付费计划增加邮箱和团队成员
## 入门指南
### 1. 安装
需要 Node 20.19 或更新版本。
```bash
npm install -g fluxmail
```
### 2. 创建 Google OAuth 凭证
Fluxmail 使用您自己的 Google Cloud OAuth 应用：
1. 在 [console.cloud.google.com](https://console.cloud.google.com) 上创建一个项目并启用 **Gmail API**（APIs & Services → Library）。
2. 配置 **OAuth 同意屏幕**：选择外部并添加您自己（以及任何其他将连接帐户的人）作为测试用户。对于自主托管，测试模式是可接受的；Google 不要求最多 100 个测试用户进行验证。
3. 创建凭证 → **OAuth 客户端 ID** → 类型 **Web 应用程序**，具有以下授权重定向 URI：
- `http://localhost:8976/oauth/callback`（由 `fluxmail accounts add gmail` 使用）
- `<your FLUXMAIL_PUBLIC_URL>/auth/google/callback`（仅当您在远程部署上使用服务器托管流程时）
Fluxmail 请求完整的 `https://mail.google.com/` 范围，因为统一 API 支持永久删除，而 Gmail 的较窄范围不允许这样做。在您的同意屏幕处于 Google 的“测试”状态时，刷新令牌将在颁发后 7 天过期，即使 Fluxmail 在此期间使用它们。当令牌过期时，请使用 `fluxmail accounts list` 查找帐户 ID，然后运行 `fluxmail accounts add gmail --reauthorize <account-id>`。您也可以将同意屏幕发布到“生产中”以获取长期令牌。
### 3. 运行 Fluxmail 并连接您的 Gmail
有两种运行方式；请选择一种。
**选项 A：本地进程（stdio）。** 个人使用在一台机器上最简单。
```bash
# 存储您的 Google 凭证；它们位于 ~/.fluxmail/config.env 中
fluxmail config set GOOGLE_CLIENT_ID <your-client-id>.apps.googleusercontent.com
fluxmail config set GOOGLE_CLIENT_SECRET <your-client-secret>
# 连接您的 Gmail（打开浏览器同意流程）
fluxmail accounts add gmail
```
**选项 B：Docker（可流式传输的 HTTP 服务器）。** 适用于共享或远程部署。镜像发布到 GitHub 容器注册表中的 [`ghcr.io/churichard/fluxmail-mcp`](https://github.com/churichard/fluxmail-mcp/pkgs/container/fluxmail-mcp)，适用于 amd64 和 arm64。
```bash
mkdir fluxmail && cd fluxmail
curl -fsSLO https://raw.githubusercontent.com/churichard/fluxmail-mcp/main/docker-compose.yml
curl -fsSL https://raw.githubusercontent.com/churichard/fluxmail-mcp/main/.env.example -o .env
# 在 .env 中填写 GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET
docker compose up -d
# 创建一个 API 密钥（显示一次）。您将在步骤 4 中将其传递给代理。
# 为方便起见，请为客户端选择一个名称，例如“laptop”。
docker compose exec fluxmail fluxmail apikey create --name laptop
# 连接您的 Gmail：打印一个同意 URL；在浏览器中打开它
docker compose exec fluxmail fluxmail accounts add gmail
```
### 4. 连接您的代理
按照步骤 3 中运行 Fluxmail 的子部分匹配。
#### 选项 A：stdio
每个客户端都启动相同的命令：`fluxmail stdio`。您的 Google 凭证来自 `fluxmail config set`（步骤 3），因此代码段不需要环境变量。两点注意：
- 桌面应用程序有时会以最小的 PATH 启动，无法找到 `fluxmail`（常见于 nvm 安装）。如果是这样，请使用 `which fluxmail` 中的绝对路径作为命令。
- 如果您跳过了 `fluxmail config set`，请在客户端的环境设置中添加 `GOOGLE_CLIENT_ID` 和 `GOOGLE_CLIENT_SECRET`。
<details>
<summary>Claude Code</summary>
```bash
claude mcp add fluxmail -- fluxmail stdio
```
</details>
<details>
<summary>Claude Desktop</summary>
添加到 `claude_desktop_config.json`（设置 → 开发者 → 编辑配置）：
```json
{
"mcpServers": {
"fluxmail": {
"command": "fluxmail",
"args": ["stdio"]
}
}
}
```
</details>
<details>
<summary>ChatGPT / Codex 应用</summary>
打开设置 -> 插件 -> MCP -> 添加服务器，然后输入：
- 名称：`Fluxmail`
- 类型：`STDIO`
- 启动命令：`fluxmail`
- 参数：`stdio`
如果应用程序找不到 `fluxmail`，请使用 `which fluxmail` 中的绝对路径作为命令。
保存，然后确保重启应用程序以使更改生效。
</details>
<details>
<summary>Codex CLI</summary>
```bash
codex mcp add fluxmail -- fluxmail stdio
```
或在 `~/.codex/config.toml` 中：
```toml
[mcp_servers.fluxmail]
command = "fluxmail"
args = ["stdio"]
```
</details>
<details>
<summary>Cursor</summary>
添加到 `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"fluxmail": {
"command": "fluxmail",
"args": ["stdio"]
}
}
}
```
</details>
<details>
<summary>Hermes</summary>
添加到 `~/.hermes/config.yaml`，然后运行 `/reload-mcp`（或使用 `hermes dashboard` 中的仪表板）：
```yaml
mcp_servers:
fluxmail:
command: 'fluxmail'
args: ['stdio']
```
</details>
<details>
<summary>Gemini CLI</summary>
添加到 `~/.gemini/settings.json`：
```json
{
"mcpServers": {
"fluxmail": {
"command": "fluxmail",
"args": ["stdio"]
}
}
}
```
</details>
<details>
<summary>VS Code（Copilot 代理模式）</summary>
在工作区中添加到 `.vscode/mcp.json`，或从命令调色板运行“MCP：添加服务器”：
```json
{
"servers": {
"fluxmail": {
"type": "stdio",
"command": "fluxmail",
"args": ["stdio"]
}
}
}
```
</details>
<details>
<summary>其他 MCP 客户端</summary>
在客户端配置中，将 `fluxmail` 注册为命令，并以 `stdio` 作为参数。
</details>
#### 选项 B：可流式传输的 HTTP
每个客户端都连接到 `http://localhost:8977/mcp`（或您的部署 URL），并使用标头 `Authorization: Bearer fmk_...` 进行身份验证，使用步骤 3 中的 API 密钥。
<details>
<summary>Claude Code</summary>
```bash
claude mcp add --transport http fluxmail http://localhost:8977/mcp \
--header "Authorization: Bearer fmk_..."
```
</details>
<details>
<summary>ChatGPT / Codex 应用</summary>
打开设置 -> 插件 -> MCP -> 添加服务器，然后输入：
- 名称：`Fluxmail`
- 类型：`Streamable HTTP`
- URL：`http://localhost:8977/mcp`
- 标头名称：`Authorization`
- 标头值：`Bearer fmk_...`
保存，然后确保重启应用程序以使更改生效。
</details>
<details>
<summary>Codex CLI</summary>
将以下内容添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.fluxmail]
url = "http://localhost:8977/mcp"
http_headers = { Authorization = "Bearer fmk_..." }
```
</details>
<details>
<summary>Cursor</summary>
添加到 `~/.cursor/mcp.json`（或项目中的 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"fluxmail": {
"url": "http://localhost:8977/mcp",
"headers": { "Authorization": "Bearer fmk_..." }
}
}
}
```
</details>
<details>
<summary>Hermes</summary>
添加到 `~/.hermes/config.yaml`，然后运行 `/reload-mcp`（或使用 `hermes dashboard` 中的仪表板）：
```yaml
mcp_servers:
fluxmail:
url: 'http://localhost:8977/mcp'
headers:
Authorization: 'Bearer fmk_...'
```
</details>
<details>
<summary>Gemini CLI</summary>
添加到 `~/.gemini/settings.json`：
```json
{
"mcpServers": {
"fluxmail": {
"httpUrl": "http://localhost:8977/mcp",
"headers": { "Authorization": "Bearer fmk_..." }
}
}
}
```
</details>
<details>
<summary>VS Code（Copilot 代理模式）</summary>
在工作区中添加到 `.vscode/mcp.json`，或从命令调色板运行“MCP：添加服务器”：
```json
{
"servers": {
"fluxmail": {
"type": "http",
"url": "http://localhost:8977/mcp",
"headers": { "Authorization": "Bearer fmk_..." }
}
}
}
```
</details>
<details>
<summary>ChatGPT 聊天（开发者模式）</summary>
上述说明为 ChatGPT 应用内的 Codex 配置了 Fluxmail。开发者模式应用程序与常规 ChatGPT 聊天有单独的连接设置。
ChatGPT 无法直接连接到 `localhost`。对于本地 Docker 服务器，请使用 OpenAI 的 [安全 MCP 隧道](https://help.openai.com/en/articles/12584461-developer-mode-and-full-mcp-connectors-in-chatgpt-beta#h_8e76ef4c26)，而不是将服务器暴露给公共互联网。您也可以在公共 HTTPS URL 上部署 Fluxmail。
ChatGPT 连接器支持 OAuth 或无身份验证；它们无法发送 Fluxmail 的静态持有者 API 密钥。在 Fluxmail 支持 MCP OAuth 之前，请仅在 `FLUXMAIL_AUTH=none` 后面运行它，并确保其位于受信任的网络或您控制的网络边界后面。然后启用开发者模式（设置 → 应用程序 → 高级设置），并创建一个指向您的 `/mcp` URL 的应用程序。
MCP OAuth 支持（这将消除此限制）已在路线图中。
</details>
<details>
<summary>其他 MCP 客户端</summary>
将客户端指向 `/mcp` URL 并发送 `Authorization: Bearer fmk_...`。无法设置授权头的客户端与 API 密钥模式不兼容；请改用受信任的网络和 `FLUXMAIL_AUTH=none`。
</details>
## 工具
| 工具 | 描述 |
| ------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| `list_accounts` | 连接的帐户，状态和功能 |
| `get_status` | 服务器健康状况：帐户，身份验证错误，计划限制 |
| `list_folders` | 文件夹/标签和角色（收件箱，已发送，草稿，...） |
| `list_emails` | 元数据和片段，可过滤（文件夹，发件人，未读，日期），分页 |
| `search_emails` | 具有相同过滤器的全文搜索 |
| `get_email` / `get_thread` | 完整正文和附件元数据 |
| `create_draft` / `update_draft` / `delete_draft` | 草稿管理，包括回复草稿 |
| `send_email` | 直接发送，发送草稿或回复（`replyToMessageId`，`replyAll`）并正确线程 |
| `forward_email` | 带有引用正文和原始附件的转发 |
| `modify_emails` | 批量：已读/未读，星标，归档，垃圾箱，移动，标签，删除 |
Fluxmail 在服务器上计算回复收件人（回复或发件人，加上原始收件人或抄送人减去您自己的地址，以便回复所有人），因此代理可以回复所有人而无需自己组装收件人列表。
## 配置
每个设置都是一个环境变量，并且有三个位置可以放置一个。在优先级顺序中：
1. shell 环境（总是赢）
2. `.env.local`，然后 `.env`，从工作目录读取
3. `fluxmail config set <KEY> <value>`，存储在 `<data dir>/config.env` 中，并且可以在任何地方运行 CLI 时使用
对于个人设置，`fluxmail config set` 最简单：设置 `GOOGLE_CLIENT_ID` 和 `GOOGLE_CLIENT_SECRET` 一次，并且每个命令和服务器模式都能找到它们。使用 `fluxmail config list` 查看存储的设置（机密值被掩盖），并使用 `fluxmail config unset <KEY>` 删除一个。
| 环境变量 | 默认值 | 目的 |
| ------------------------------------------- | --------------------------------- | ------------------------------------------------------------------ |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | （需要 Gmail） | 您的 Google OAuth 应用 |
| `FLUXMAIL_DATA_DIR` | `~/.fluxmail`（Docker 中的 `/data`） | SQLite 数据库和自动生成的加密密钥 |
| `FLUXMAIL_ENCRYPTION_KEY` | 自动生成 | 64 个十六进制字符；静态存储 OAuth 令牌 |
| `FLUXMAIL_PORT` | `8977` | HTTP 端口 |
| `FLUXMAIL_PUBLIC_URL` | `http://localhost:8977` | 公共 URL，用于 OAuth 重定向 URI |
| `FLUXMAIL_AUTH` | `apikey` | `none` 禁用 MCP 身份验证（仅限受信任的网络） |
| `FLUXMAIL_OAUTH_PORT` | `8976` | CLI OAuth 流的环回端口 |
| `FLUXMAIL_OAUTH_HOST` | `127.0.0.1` | OAuth 侦听器绑定地址（Docker 中的 `0.0.0.0`） |
| `FLUXMAIL_LICENSE_KEY` | （无） | 付费计划许可证密钥；通常通过 `fluxmail license activate` 设置 |
## CLI
在 Docker（选项 B）下运行？在这些命令前加上 `docker compose exec fluxmail`，以便在容器内运行命令，例如 `docker compose exec fluxmail fluxmail accounts list`。
```
fluxmail serve # HTTP 服务器（MCP 在 /mcp）
fluxmail stdio # stdio MCP 服务器
fluxmail accounts add gmail # OAuth 同意流程；添加 --member <id-or-email> 以设置所有者
fluxmail accounts add gmail --reauthorize <account-id>
fluxmail accounts list | remove <id>
fluxmail accounts assign <id> --member <id-or-email> # 或 --shared
fluxmail members add --name <name> [--email <email>] # 使用此实例的人员
fluxmail members list | remove <id>
fluxmail apikey create --name <name> # 密钥用于 HTTP 端点（显示一次）；以使用它的客户端命名
fluxmail apikey create --name <name> --member <id-or-email>
fluxmail apikey list | revoke <id>
fluxmail config set <KEY> <value> # 在数据目录中持久化设置
fluxmail config list | unset <KEY>
fluxmail license activate <key> # 解锁付费计划限制
fluxmail license status | deactivate
fluxmail status
```
## 架构
```
packages/
core/ # 统一类型，EmailQuery 语言，EmailProvider 接口
provider-gmail/ # Gmail 适配器（googleapis）：查询转换，MIME，线程，标签
server/ # EmailService，SQLite 存储，OAuth，MCP 工具，HTTP + stdio 传输，CLI
```
MCP 工具是 `EmailService` 的薄包装，它拥有帐户路由、回复和转发计算以及计划限制。未来的 REST API 或扩展的 CLI 将调用相同的服务。每个提供程序实现一个 `EmailProvider` 接口并声明一个 `capabilities` 对象，以便在提供程序不同的情况下，工具可以干净地降级（例如，IMAP 没有标签）。
## 计划
在 **个人** 计划上自主托管是免费的：3 个连接的邮箱和 1 个成员。付费计划（Pro、Team、企业）提高了这些限制，适用于共享一个实例的团队；每个人连接自己的邮箱，一个邮箱也可以被共享。请参阅 [fluxmail.ai](https://fluxmail.ai) 获取当前定价。
付费计划通过 `fluxmail license activate <key>` 解锁。一个许可证激活一个实例，并且执行保持有效，即使离线。如果许可证过期，实例将恢复到个人限制。停用、降级或过期都不会删除帐户或数据。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器