通过 MCP 将 AI 智能体连接到 TrekMail

TrekMail MCP 服务器让兼容的 AI 客户端能够通过自然语言管理您的电子邮件基础设施。其目录涵盖域名、邮箱、White Label 品牌和团队、Drive、电子邮件、日历、迁移、支持、计费及相关服务，并统一使用 TrekMail API。

并非每次对话都会加载完整目录。TrekMail 根据当前凭据构建 tools/list：超出其权限范围的工具会被省略，由所选工具集、只读模式、传输限制或本地安全设置排除的工具同样不会出现。因此，权限范围严格限定的电子邮件凭据只会显示精简的电子邮件工具列表。

选择连接方式

路径 1-3 使用 OAuth 2.1：首次连接时，浏览器会打开 TrekMail 的同意页面，您可查看请求的权限，客户端随后获得仅限您账户范围的令牌。无需把长期有效的 tm_live_ 令牌复制到客户端。您可以随时在 AI 智能体与 API → 令牌 → 已连接的应用 中撤销连接。

您将获得

• 连接专属工具集，在注册前按当前连接的权限和安全设置完成筛选。
• **OAuth 2.1 + 动态客户端注册：**AI 客户端会自行注册，引导您完成浏览器同意页面，并获得限定范围的令牌。网页、桌面或 CLI 路径都无需复制粘贴长期令牌。
• **双令牌架构：**将运维令牌（基础设施）与消息令牌（完整 Webmail 操作）分开。通过 OAuth 连接时，系统会按需自动为每个邮箱生成消息令牌。
• 自动幂等处理用于需要此特性的操作，确保重试不会重复执行同一操作。
• **两步删除：**删除邮箱需要明确表达意图并确认，然后邮箱会移至“最近删除”以便恢复。
• **自托管安全控制：**运行自有 stdio MCP 服务器的管理员可要求对删除、发送和迁移操作进行批准。
• **完整审计日志：**每项 API 和 MCP 操作都会记录并保留 90 天。

开始之前

• 所有套餐均可连接智能体。
  • **Nano：**Email Verifier 工具。添加 Drive Storage 后，智能体还可使用账户有权使用的 Drive 功能，包括浏览、上传、共享、恢复和彻底删除。
  • **Starter：**完整 Drive、完整 Email Verifier，以及其余领域（域名、邮箱、迁移、工单等）的只读访问权限。对于 Starter 未通过 API 开放的写入操作，如创建迁移、回复工单或更改自动回复，请使用控制面板。
  • **Pro / Agency：**所有工具系列的完整读写权限。
  • **White Label 试用或附加服务：**权益有效期间会添加品牌、客户/团队和活动工具。没有该权益时，这些架构会被省略。在取消宽限期内，只有所有者能继续使用读取工具。
• 首次使用？ AI 智能体与 API 页面上的 开始导览 按钮会介绍智能体连接、各客户端步骤、手动令牌、已连接应用和审计日志。
• 对于 OAuth 路径 (1, 2, 3)，您无需手动创建令牌。客户端会通过浏览器授权流程创建令牌。对于 自托管 stdio 路径 (4)，请先在控制面板中创建 tm_live_ 令牌。

1. 远程 MCP 客户端（推荐）

当您的 AI 客户端支持远程 MCP 服务器和浏览器授权时，请使用此路径。

**快捷方式：**AI 智能体与 API 页面的 连接智能体 标签页会询问您使用的客户端， 随后显示该客户端的确切路径、菜单位置，或者配置文件及已填入 您地址的现成代码段。如果列表中有您的客户端，请按照其中的说明操作，而不是采用下方的 通用步骤。

1. 在客户端中打开 MCP、集成或连接器设置。
2. 选择 添加远程 MCP 服务器 或 添加自定义连接器。具体标签因客户端而异。
3. 输入：
   • 名称：TrekMail
   • 远程 MCP 服务器 URL：https://trekmail.net/mcp
4. 确认连接。浏览器会打开 TrekMail 授权页面。
5. 登录、查看请求的权限并批准访问。浏览器确认连接后返回客户端。

首次授权会签发一个限时令牌。兼容的客户端会自动刷新令牌。若要断开连接，请使用客户端的断开操作，或在 TrekMail 的 令牌 → 已连接的应用 中撤销该应用。

2. CLI 或桌面客户端

对于接受 stdio 命令的客户端，请使用下面这个不依赖特定客户端的桥接器：

npx -y mcp-remote https://trekmail.net/mcp

在客户端中将该命令配置为 MCP 服务器。首次连接会打开浏览器进行授权。

有些客户端还提供自己的远程 MCP 服务器添加命令，同样可以使用；将 https://trekmail.net/mcp 设为服务器 URL，并按照客户端提示操作。

客户端专用示例：Claude Code

claude mcp add trekmail https://trekmail.net/mcp -t http

客户端专用示例：Claude Desktop

编辑配置文件（macOS：~/Library/Application Support/Claude/claude_desktop_config.json · Windows：%APPDATA%\Claude\claude_desktop_config.json），然后添加：

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp",
      "transport": "http"
    }
  }
}

重新启动 Claude Desktop。首次在聊天中提到 TrekMail 时，会打开 OAuth 弹窗。

客户端专用示例：Cursor

Cursor 没有远程服务器设置界面。它会读取 ~/.cursor/mcp.json（或项目中的 .cursor/mcp.json ）：

{
  "mcpServers": {
    "trekmail": {
      "url": "https://trekmail.net/mcp"
    }
  }
}

客户端专用示例：Windsurf

Windsurf 会读取 ~/.codeium/windsurf/mcp_config.json。请注意，键名是 serverUrl，而不是 url； 使用 url 配置的远程服务器会被忽略：

{
  "mcpServers": {
    "trekmail": {
      "serverUrl": "https://trekmail.net/mcp"
    }
  }
}

保存文件并重启客户端，以便加载更改。首次连接会打开 浏览器供您批准访问。

3. mcp-remote (CLI)

对于测试或尚未直接支持远程 OAuth 服务器的非 Anthropic MCP 客户端，mcp-remote 非常实用。它是一个从 stdio 连接到远程 HTTP 的小型 Node 桥接器。

npx -y mcp-remote https://trekmail.net/mcp

首次运行时会打开浏览器进行 OAuth。之后，令牌会缓存在 ~/.mcp-auth/ 下并自动使用。

您可以让任何 stdio MCP 客户端指向 mcp-remote 命令，而非本地 Node 入口点，从而完成连接。

4. 自托管 stdio (Claude Desktop / Docker / npm)

如果您希望使用静态 tm_live_ 令牌而非 OAuth（例如用于无人值守服务器、私有 TrekMail 实例或容器部署），请克隆 stdio MCP 软件包并在自己的主机上运行。

请先在 AI 智能体与 API → 令牌 页面创建 API 令牌。若要读取/发送电子邮件，还需使用运维令牌通过 API 创建消息令牌（说明请参阅 连接智能体 标签页）。

安装 MCP 服务器

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install
npm run build

Claude Desktop (stdio)

将以下内容添加到 Claude Desktop MCP 配置文件：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

更新 args 路径，使其指向您克隆仓库的位置。将示例令牌替换为您自己的令牌。如果只需要基础设施工具，可以省略 TREKMAIL_MESSAGE_TOKEN；如果只需要消息工具，可以省略 TREKMAIL_API_TOKEN。必须至少提供一个令牌。

Claude Code (stdio)

将以下内容添加到 Claude Code MCP 设置（.claude/settings.json 或项目级配置）：

{
  "mcpServers": {
    "trekmail": {
      "command": "node",
      "args": ["./trekmail-mcp/build/index.js"],
      "env": {
        "TREKMAIL_BASE_URL": "https://trekmail.net",
        "TREKMAIL_API_TOKEN": "tm_live_your_token",
        "TREKMAIL_MESSAGE_TOKEN": "tm_msg_your_token",
        "TREKMAIL_ALLOW_SENDING": "false",
        "TREKMAIL_ALLOW_MIGRATION": "false"
      }
    }
  }
}

Docker

如果您更喜欢 Docker，请从仓库构建镜像并运行：

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
docker build -t trekmail-mcp .

docker run -i \
  -e TREKMAIL_BASE_URL=https://trekmail.net \
  -e TREKMAIL_API_TOKEN=tm_live_your_token \
  -e TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
  -e TREKMAIL_ALLOW_SENDING=false \
  -e TREKMAIL_ALLOW_MIGRATION=false \
  trekmail-mcp

本地 npm（开发）

git clone https://github.com/trekmail/mcp-server trekmail-mcp
cd trekmail-mcp
npm install && npm run build

TREKMAIL_BASE_URL=https://trekmail.net \
TREKMAIL_API_TOKEN=tm_live_your_token \
TREKMAIL_MESSAGE_TOKEN=tm_msg_your_token \
TREKMAIL_ALLOW_SENDING=false \
TREKMAIL_ALLOW_MIGRATION=false \
npm start

Stdio 环境变量

这些控制项仅适用于您运行的自托管 stdio MCP 进程，不会启用或停用 TrekMail 产品功能。

面向智能体的 Drive 工具

使用包含 Drive 权限范围的运维令牌时，MCP 服务器会提供空间、用量、浏览、上传、文件、文件夹、垃圾箱、批量操作、公共共享链接、同步设备密码管理以及 Drive Add-on 状态工具。您的连接只会看到其权限范围允许的工具。

对于仅使用 Drive 的智能体，请设置 TREKMAIL_API_TOKEN，并只授予工作流所需的权限范围。如果运行自托管 stdio，请保持禁用破坏性操作，除非智能体正在执行经过审核的彻底删除或清空垃圾箱任务。购买、调整或取消 Drive Add-on 并非 MCP 工具；智能体可以读取附加服务状态和价格，但计费更改仍需在控制面板中完成。

请参阅 Drive MCP 工具概览 和 将 AI 智能体连接到 TrekMail Drive。

可用工具

MCP 服务器向已连接的智能体提供以下工具。系统会根据提供的令牌有条件地注册工具。

智能体实际能看到哪些工具由三个因素决定，并在 tools/list 响应前全部应用：

1. **令牌的权限范围。**如果令牌不包含某项工具所需的功能，该工具绝不会被注册。
2. **本地 stdio 安全控制。**运行自托管 stdio 服务器时，管理员可以要求批准写入、发送或迁移操作。托管 MCP 则使用 OAuth 期间批准的权限范围。
3. TREKMAIL_READ_ONLY=true，无论权限范围和标志如何，它都会移除所有写入工具。

因此，即使令牌拥有更广的权限范围，也可以有意限制自托管连接。托管 MCP 始终受 OAuth 期间批准的权限限制。

域名工具（运维令牌）

有关套餐行为、响应状态、安全移除和仅接收路由规则，请参阅 通过 API 和 MCP 使用域名别名。

White Label 工具（运维令牌）

white_label 工具集包含 20 个工具，仅当账户权益、当前成员资格和凭据权限范围均允许时才会出现。品牌按域名配置；其余工具用于管理设置、客户、团队访问权限和活动。写入需要有效的 White Label。在取消宽限期内，只有所有者保留读取工具。

智能体可以端到端完成品牌设置：设置品牌、复制返回的 dns_records、使用 apply_cloudflare_dns 发布，然后验证并检查状态。即使令牌请求了更广的权限范围，更改访问权限的调用仍受调用方当前成员资格和域名边界限制。请参阅 White Label 品牌 API 和 MCP 指南 以及 使用 API 和 MCP 管理 White Label 团队。

DNS 工具（运维令牌）

邮箱工具（运维令牌）

共享邮箱工具（运维令牌）

共享邮箱是团队收件箱（support@、sales@），成员可通过自己的普通邮箱账户在 Webmail 中打开；启用后，也可通过委派的原生 IMAP/SMTP 访问。它没有直接密码登录。访问权限是统一的，每个人都能读取，can_send 是唯一开关（可回复或只读）。没有成员角色。

共享邮箱生命周期（运维令牌）

三个生命周期工具和三个成员写入工具都会更改访问权限。本地托管的 stdio 管理员可以要求先设置 TREKMAIL_ALLOW_DESTRUCTIVE=true 才提供这些工具；list_shared_mailbox_members 为只读，始终可用。

创建、转换或更改成员资格后，使用普通成员邮箱 id 调用 get_mail_client_setup。读取 shared_mailboxes.items[]，等待 native_access_ready=true，并在配置发送前检查 send_as_ready。响应会提供确切的收件箱/已发送/归档/垃圾邮件路径和操作标志；SMTP 不会保存共享的已发送副本。如果移除权限、更新权限或转换时返回可重试的 native_access_sync_failed，则表示服务有意保留了之前的状态。

Sieve 工具（运维令牌）

删除工具（运维令牌）

迁移工具（运维令牌）

工单工具（运维令牌）

SMTP / 域名路由工具（运维令牌）

SMTP 按域名配置：每个域名可以使用平台托管发送，也可以指向保存的 SMTP 配置文件（您自己的提供商，可跨域名重复使用）；一个账户级默认设置决定新域名的初始配置。

上述写入和测试工具会更改设置或执行连接测试。本地托管的 stdio 管理员可要求先设置 TREKMAIL_ALLOW_DESTRUCTIVE=true 才提供这些工具；get_domain_smtp、list_domain_smtp_profiles、get_domain_smtp_test_status 和 get_account_smtp_default 为只读，始终可用。

旧版 SMTP 工具（已弃用）

这些账户级工具为向后兼容而保留，但不再控制每个域名的路由：请改用上述域名路由工具。

垃圾邮件指标工具（运维令牌）

账户工具（运维令牌）

消息令牌管理（运维令牌）

消息工具（消息令牌）

消息令牌可解锁 62 个工具，覆盖完整的 Webmail 功能，包括已连接的外部账户。工具按功能领域组织。

托管 OAuth 和本地 stdio 以不同方式识别邮箱。在托管 HTTP MCP 上，每个消息工具架构都包含必填的 mailbox_id；服务器用它为该邮箱生成短期令牌。在本地 stdio MCP 上，TREKMAIL_MESSAGE_TOKEN 已绑定到一个邮箱，因此这些工具不接受 mailbox_id。已连接的收件箱是第二级选择：传递 external_account_id；在托管 MCP 上，它与 mailbox_id 一起使用，在 stdio 上则与绑定的消息令牌一起使用。

62 个消息工具中有七个用于管理已连接账户，另有五个用于管理发件身份和回复策略。两类工具结合后，可实现类似 Gmail 的工作流：智能体读取已连接的 Gmail 收件箱，但通过域名路由或保存的 SMTP 配置文件，以获准的企业地址发送邮件。请参阅 通过 API 和 MCP 使用发件身份地址。

核心消息

如果邮箱在“设置 → 个人资料”中设有默认抄送或默认密送，它会添加到 send_message 和 schedule_message 的发件内容中，与 Web 应用内撰写的邮件完全相同；消息中已有的地址不会重复添加。传递 apply_default_recipients: false 可为单封消息停用此功能。这不会影响桌面或手机邮件客户端通过 SMTP 发送的邮件，因为这些邮件从不经过 API。 | report_spam | 将消息举报为垃圾邮件，移至垃圾邮件文件夹并训练过滤器 | | report_ham | 将垃圾邮件文件夹中的消息标记为正常邮件，移至收件箱并训练过滤器 | | bulk_action | 一次对最多 50 封消息执行操作（已读、加星、删除、移动、垃圾邮件） |

文件夹

附件

草稿

两者都会返回草稿的 uid 和 uidvalidity。请始终一起保存这两个值：update_draft 要求提供纪元，确保“草稿”文件夹重新创建后，旧的重用 UID 永远不会删除其他消息。通过 list_messages 找到的草稿应先用 read_message 打开，它会返回当前的 uidvalidity。更新会返回一组新的值，旧 UID 随即失效。在没有 UIDPLUS 的服务器上，即使新草稿已保存，这两个值也可能为 null；请刷新“草稿”并打开草稿后再更新。

两者还接受可选的 idempotency_key。如果省略，每次调用都会被视为新操作，因此将同一草稿保存两次会得到两份草稿。重试可能已经成功的调用时，请传递相同的密钥；系统会返回首次结果，而不是创建副本。

定时发送

联系人

联系人组

日历

撰写辅助工具

这些工具为回复或转发准备数据，不会发送任何内容。请将返回的数据直接传给 send_message 或 save_draft。

身份（发件地址）

模板

已屏蔽的发件人

Email Verifier 工具（运维令牌）

Email Verifier 工具适用于所有套餐，包括 Nano。唯一的限制是您的积分余额。

Cloudflare 工具（运维令牌）

Cloudflare 工具适用于 Pro 和 Agency 套餐。

自托管 stdio 的安全控制

自行运行 stdio MCP 服务器时，TREKMAIL_ALLOW_DESTRUCTIVE 控制该本地进程是否允许删除和其他写入操作。仅当您信任智能体能够妥善处理邮箱删除时，才将其设为 true。此设置不会改变托管 TrekMail 中的功能可用性。

即使启用了破坏性操作，删除仍始终需要两个步骤，而且智能体必须明确设置 confirm: true。详情请参阅 安全屏障与删除意图。

发送安全屏障

send_message 和 schedule_message 工具有两个独立的安全屏障，二者都必须通过：

1. **环境屏障：**启动 MCP 服务器时必须设置 TREKMAIL_ALLOW_SENDING=true。
2. **每次调用屏障：**智能体必须在每次调用中传递 confirm_send=true 参数。

这种双屏障设计可防止自托管进程意外发送电子邮件。如果智能体只应读取消息，请设置 TREKMAIL_ALLOW_SENDING=false。list_scheduled 无需此控制即可运行；该控制仅适用于创建或发送定时消息。

迁移安全屏障

迁移写入工具（start_migration、retry_migration、delete_migration、delete_bulk_migration、update_bulk_migration_job_password、test_migration_connection、preview_bulk_migration、start_bulk_migration、retry_bulk_migration）具有两个独立的安全屏障：

1. **环境屏障：**启动 MCP 服务器时必须设置 TREKMAIL_ALLOW_MIGRATION=true。
2. **每次调用屏障：**每个工具都需要自己的确认参数（confirm_start=true、confirm_retry=true 或 confirm_delete=true）。

无论自托管环境控制如何，cancel_migration、cancel_bulk_migration 和 resume_bulk_migration 始终可用，因为它们属于安全或恢复操作。它们仍需要每次调用的确认参数。

只读迁移工具（list_migrations、get_migration、list_bulk_migrations、get_bulk_migration）无需任何屏障即可运行。

快速修复

• **智能体无法连接：**请确认 build/index.js 路径正确，并且克隆后已运行 npm run build。
• **出现 "Missing bearer token" 错误：**请检查是否至少设置了 TREKMAIL_API_TOKEN 或 TREKMAIL_MESSAGE_TOKEN 之一。
• **只读工具可用但写入失败：**您的令牌属于 Starter 套餐。Starter 支持 Drive 写入（完整 Drive 功能）。对于其他写入、邮箱配置、启动迁移或回复工单，请升级到 Pro 或使用控制面板。
• **自托管 stdio 中的删除工具返回错误：**在该 MCP 进程的环境中设置 TREKMAIL_ALLOW_DESTRUCTIVE=true。这适用于删除及其他写入操作，包括消息、文件夹、联系人、日历、身份、模板、已屏蔽发件人和定时消息。
• **自托管 stdio 发送工具返回 "Sending is disabled"：**在该 MCP 进程的环境中设置 TREKMAIL_ALLOW_SENDING=true。
• **发送工具返回 "Send not confirmed"：**智能体必须传递 confirm_send=true，并在每次调用 send_message 或 schedule_message 时这样做。
• **没有出现消息工具：**请确保 TREKMAIL_MESSAGE_TOKEN 已设置为有效的 tm_msg_ 令牌。
• **自托管 stdio 迁移写入工具返回错误：**在该 MCP 进程的环境中设置 TREKMAIL_ALLOW_MIGRATION=true。
• **启动迁移时出现 503：**服务器已达到迁移容量。请过几分钟重试。
• **附件下载失败：**附件以 base64 返回。大型附件（最大 25 MB）可能需要几秒钟。download_all_attachments 会返回包含所有附件的 base64 编码 ZIP。
• 更新后草稿消失：update_draft 会删除旧草稿并附加替代草稿，因此草稿会获得新的 UID 标识。后续操作请同时使用响应中的 uid 和 uidvalidity；您传入的那组值已无法标识替代草稿。
• **每封消息的副本都到达了未指定的位置：**该邮箱在“设置 → 个人资料”中设有默认抄送或默认密送。它适用于该邮箱发送的内容，包括通过 API 发送的内容。请在那里清除，或传递 apply_default_recipients: false 以便对单封消息停用。
• **找不到日历事件：**事件仅限于特定邮箱。请确认消息令牌是为正确的邮箱签发的。