Mektup-mcp

Mektup MCP 服务

Mektup 是一个完全托管的多域名电子邮件平台——Mektup 托管所有邮件基础设施，因此无需自行托管；只需注册并开始使用。此 MCP 服务让 AI 编码 Agent（Claude Code、Claude Desktop、Cursor、Lovable、Replit、Base44，或任何兼容 MCP 的客户端）能够为某个域名管理真实邮件——注册域名、添加 DNS 记录、创建邮箱、发送和阅读邮件、管理草稿/联系人/文件夹/转发/休假自动回复——并将这些操作作为原生工具调用在自己的会话中执行，无需人工手写 curl 命令，也无需将 API 密钥粘贴到生成的代码中。

每次工具调用都会直接向真实的 Mektup REST API 发起 HTTP 请求。无需额外学习其他逻辑——了解 API，就了解这个 MCP 服务。全面覆盖：每个 REST 端点都有对应的工具，并已通过实时生产 API 上真实的读写往返操作进行验证（创建 → 更新 → 列出 → 删除，每一步均已确认）。

有两种运行方式，两者使用相同的工具集（lib/build-server.js 一次性定义工具，供两者共用）：

• 远程（Streamable HTTP）——我们托管的服务，地址为 https://mcp.usemektup.com/mcp。任何支持“自定义 MCP 服务”URL 的客户端都可以直接连接，无需安装。这适用于 Lovable/Cursor/Replit/Base44 这类平台。
• 本地（stdio）——将密钥放在环境变量中，自行运行 server.js。适用于只支持启动本地进程的 MCP 客户端（例如 Claude Desktop 配置等）。

---

远程服务（推荐用于平台集成）

端点： https://mcp.usemektup.com/mcp（Streamable HTTP——同时支持规范中的直接 JSON 响应模式和 SSE 流式响应模式）。

无状态： 请求之间不会保留会话——每次工具调用本身就是对 REST API 的一次性转发，因此没有值得保留的会话状态。

租户隔离： 与 REST API 完全相同，因为底层本身就是 REST API——服务本身不持有任何账户专属凭据，只会将调用方发送的令牌（API 密钥或 OAuth 访问令牌，见下文）直接转发到 api.usemektup.com，只有该处会实际验证令牌。令牌只能访问其所属账户的数据。

两种身份验证模式使用相同的端点，并且都会通过相同的 Authorization: Bearer <token> 标头传递：

OAuth（推荐用于平台集成）

适用于拥有真实终端用户的平台（Lovable、Cursor、Replit、Base44 等）——用户点击“连接”，使用现有的 Mektup 账户登录并授权，操作即告完成。无需复制粘贴令牌，也无需访问控制面板。

Clerk（clerk.usemektup.com）是 OAuth 2.1 授权服务端——此 MCP 服务始终只是资源服务端。对于任何符合规范且支持 OAuth 的 MCP 客户端，发现流程都是自动的：客户端只需使用上方的端点 URL，即可通过 https://mcp.usemektup.com/.well-known/oauth-protected-resource/mcp（RFC 9728）自动发现其余信息；该地址指向 Clerk 自己的 https://clerk.usemektup.com/.well-known/oauth-authorization-server（RFC 8414）。之后，客户端会通过动态客户端注册流程自行注册（你无需手动设置），并运行标准的授权码 + PKCE 流程，最终获得一个使用方式与 API 密钥完全相同的 JWT 访问令牌。

Lovable： Connectors → All → Custom（MCP 卡片）→ Server Name Mektup，Server URL https://mcp.usemektup.com/mcp，Auth → OAuth（服务器支持时的默认选项）→ Add & authorize。

API 密钥（适用于单个账户、脚本或不支持 OAuth 的客户端，设置最简单）

Authorization: Bearer mek_live_... — 在 app.usemektup.com → API keys 中创建。

在支持自定义 MCP 连接器的客户端中添加密钥，通常只需填写 3 个字段：

字段	值
服务 URL	https://mcp.usemektup.com/mcp
身份验证类型	Bearer 令牌 / API 密钥
令牌	你的 mek_live_... 密钥

Cursor / Claude Desktop / 任何读取原始 MCP JSON 配置的客户端：

{
  "mcpServers": {
    "mektup": {
      "url": "https://mcp.usemektup.com/mcp",
      "headers": { "Authorization": "Bearer mek_live_..." }
    }
  }
}

**Replit / Base44 / 其他“连接工具”流程：**填写与上表相同的三个字段——服务 URL、Bearer 身份验证和密钥。

---

本地（stdio）设置

当客户端只能启动本地进程、无法调用远程 URL 时，请使用此方式。

**1. 获取 API 密钥。**登录 app.usemektup.com 控制面板，打开 API keys 并创建密钥。密钥格式为 mek_live_...，且只会显示一次——请立即复制。

2. 安装依赖项：

git clone https://github.com/WeeCi/mektup-mcp.git
cd mektup-mcp
npm install

3. 配置 MCP 客户端，使其使用密钥作为环境变量运行 server.js。对于 Claude Desktop / Claude Code，请将以下内容添加到 MCP 配置中（例如 claude_desktop_config.json）：

{
  "mcpServers": {
    "mektup": {
      "command": "node",
      "args": ["/absolute/path/to/mektup-mcp/server.js"],
      "env": {
        "MEKTUP_API_KEY": "mek_live_..."
      }
    }
  }
}

MEKTUP_API_BASE_URL 是可选项，默认值为 https://api.usemektup.com——正常使用时无需设置。

未设置 MEKTUP_API_KEY 时，服务将拒绝启动。

---

工具如何响应

成功时，每个工具都会将结果作为 JSON 文本返回。失败时，则会返回 isError: true 和 Error: <message>——其中的消息与底层 REST 端点返回的消息相同（具体错误情况，包括各端点的账单限额 402 错误，请参阅 API 参考）。

---

工具

账户

工具	输入	说明
get_me	—	获取已通过身份验证的账户身份信息。可用于检查身份验证状态。
get_usage	—	当前账单套餐、套餐限额及实际用量。执行批量操作前请先检查。

API 密钥

工具	输入	说明
list_api_keys	—	列出此账户的密钥（仅显示前缀和状态）。
create_api_key	—	创建新密钥。完整密钥只会返回一次——请立即向用户显示，以便他们保存。
revoke_api_key	id	立即撤销密钥。此操作无法撤销——请先与用户确认，尤其是该密钥可能正被本次会话使用时。

域名

工具	输入	说明
create_domain	domain	注册域名，获取准确的 DNS 记录（MX/SPF/DMARC/DKIM）和设置建议。此操作不会修改 DNS。
list_domains	—	列出此账户下的所有域名。
get_domain_records	domain	域名注册后，可随时重新获取其 DNS 记录。
verify_domain	domain	主动重新检查实时 DNS，并在记录匹配后将域名标记为已验证。不会自动执行。
delete_domain	domain	删除域名及其下的所有内容。此操作具有破坏性——请先与用户确认。

邮箱

工具	输入	说明
create_mailbox	domain, localPart, password?	创建邮箱，获取真实的 IMAP/SMTP-AUTH 凭据，可在任何邮件客户端中使用。
list_mailboxes	domain	列出域名下的邮箱。
reset_mailbox_password	domain, localPart, password?	重置邮箱的登录密码。密码只显示一次。
delete_mailbox	domain, localPart	删除邮箱。请先与用户确认。

Webhooks

工具	输入	描述
get_mailbox_webhook	domain, localPart	检查邮箱已配置的 Webhook URL（绝不会返回签名密钥）。
set_mailbox_webhook	domain, localPart, url, regenerateSecret?	设置/更新 URL：每收到一封新邮件时都会触发（使用 HMAC 签名），让 Agent 无需轮询 list_messages 就能获知新邮件。首次设置或轮换密钥时，会返回一次签名密钥。
delete_mailbox_webhook	domain, localPart	删除邮箱的 Webhook。

转发

工具	输入	描述
list_forwards	domain, localPart	列出会收到来信副本的地址。
add_forward	domain, localPart, forwardTo	添加转发地址。
remove_forward	domain, localPart, id	删除转发地址。

身份信息

工具	输入	描述
get_identity	domain, localPart	获取显示名称和签名。
set_identity	domain, localPart, displayName?, signatureText?, signatureHtml?	设置显示名称/签名，并自动应用于发出的邮件。

假期 / 自动回复

工具	输入	描述
get_vacation	domain, localPart	获取假期自动回复设置。
set_vacation	domain, localPart, enabled, subject?, message?	启用/配置自动回复。启用时必须提供 message。

文件夹

工具	输入	描述
list_folders	domain, localPart	列出自定义文件夹。
create_folder	domain, localPart, name	创建文件夹。
delete_folder	domain, localPart, id	删除文件夹（其中的邮件会归入收件箱/已发送）。

联系人

账户级别，而非每个邮箱单独设置。

工具	输入	描述
list_contacts	—	列出联系人。
create_contact	name?, email	添加联系人。
update_contact	id, name?, email?	部分更新——仅发送需要更改的字段。
delete_contact	id	删除联系人。

草稿

工具	输入	描述
list_drafts	domain, localPart	列出草稿（仅元数据）。
get_draft	domain, localPart, id	获取草稿，包括正文。
create_draft	domain, localPart, to?, subject?, text?, html?	创建草稿。
update_draft	domain, localPart, id, to?, subject?, text?, html?	部分更新（适合自动保存）。
delete_draft	domain, localPart, id	删除草稿。

发送

工具	输入	描述
send_email	from, to, subject, text?, html?, attachments?, draftId?	发送真实邮件。from 必须是此账户下的邮箱，或此账户已验证域名上的任意地址。附件格式为 {filename, contentType?, contentBase64}，解码后每个附件最大为 10 MB。传入 draftId 可在发送成功后删除草稿。

示例：

send_email({ from: "[email protected]", to: "[email protected]", subject: "It works", text: "Real mail, sent through Mektup." })
→ { "messageId": "<[email protected]>", "envelope": { "from": "[email protected]", "to": ["[email protected]"] } }

消息和会话

工具	输入	描述
list_messages	mailbox, limit?, direction?, trash?, folder?, q?	列出消息（每个会话一行）。传入 direction 可分别列出收件箱和已发送邮件；不传则合并显示。
get_delivery_stats	mailbox, days?	汇总邮箱的外发邮件中已发送、延迟、退回和未知状态的数量，数据来自 Mektup 自己的 Postfix 投递日志，而非跟踪像素。
get_thread	threadKey, mailbox, direction?, trash?, folder?	获取一个会话中的所有消息，按时间从早到晚排列。
get_message	id	获取完整消息内容。此操作会将消息标记为已读。html 由攻击者控制，切勿直接渲染。
update_message	id, read?, restore?, flagged?, folderId?	将消息标记为已读或未读、从垃圾箱恢复、加旗标或移至文件夹，可在一次调用中组合执行任意操作。
delete_message	id	两阶段删除：首次调用将消息移至垃圾箱；对已在垃圾箱中的消息再次调用则会永久删除。永久删除前请先确认。
download_attachment	id, index	下载一个附件，内容以 base64 编码。仅在确实需要文件内容时使用；get_message 返回的附件列表已包含文件名、类型和大小。

账户范围

工具	输入	描述
get_unread_counts	—	一次获取每个域名和邮箱的未读收件箱数量。

---

另请参阅

• 完整 REST API 参考 — 此服务封装的所有功能
• OpenAPI 3.1 规范 — 同一 API 的机器可读版本
• usemektup.com — 注册、查看控制面板和定价

许可证

MIT