1. 项目概述：Lettr MCP Server 是什么？

如果你是一名开发者，日常工作中免不了要和邮件打交道——用户注册的欢迎信、密码重置的确认函、订单状态的实时通知，这些都属于“事务性邮件”的范畴。传统的做法是，在代码里硬编码邮件内容，或者调用某个邮件服务商的API，然后在IDE和邮件服务商的控制台之间来回切换，调试起来相当繁琐。最近，我深度体验了一个名为 Lettr MCP Server 的开源项目，它彻底改变了我的工作流。简单来说，这是一个基于 Model Context Protocol 的服务器，它能让你直接在 Claude Desktop 、 Cursor 或 Claude Code 这类AI编程助手内部，无缝地调用Lettr邮件服务的所有功能。

想象一下这个场景：你正在用Cursor写一段用户注册的后端逻辑，写到“发送验证邮件”这一步时，不再需要离开编辑器去查API文档或打开网页控制台。你只需在AI助手的聊天框里输入：“帮我用模板‘welcome_email’给新用户 user@example.com 发封欢迎邮件，把 {{name}} 替换成‘张三’。” AI助手会通过这个MCP Server，直接调用Lettr的API完成发送，并将结果反馈给你。整个过程流畅得就像在和一个懂邮件系统的同事对话。这个项目的核心价值，就是将邮件发送、模板管理、域名配置等原本离散的操作，深度集成到了你的开发环境中，实现了“所想即所得”的邮件操作体验。

2. 核心原理与架构拆解

要理解Lettr MCP Server为何高效，我们需要拆解其背后的两个核心概念： Model Context Protocol 和 Lettr邮件服务 。

2.1 Model Context Protocol：AI能力的“插件”标准

MCP，你可以把它理解为AI助手（如Claude）的“USB接口”标准。在没有MCP之前，AI助手的能力受限于其训练数据和内置功能，无法直接操作外部系统（如你的邮件服务、数据库、项目管理系统）。MCP定义了一套标准协议，允许外部服务器（即MCP Server，如Lettr MCP Server）以“工具”的形式，将自己的能力暴露给AI客户端。

工作流程如下 ：

1. 注册 ：你在AI客户端（如Claude Desktop）的配置文件中，声明要使用Lettr MCP Server，并附上你的API密钥。
2. 连接 ：AI客户端启动时，会根据配置启动Lettr MCP Server进程，两者通过标准输入输出或HTTP建立连接。
3. 发现 ：AI客户端向Server询问：“你有哪些工具可用？” Server返回一个工具列表，例如 send-email , list-templates 等。
4. 调用 ：当你在聊天中提出与邮件相关的需求时，AI客户端会理解你的意图，选择对应的工具，构造参数，并通过MCP协议调用Server。
5. 执行与返回 ：Server接收到调用后，使用你提供的API密钥，向真正的Lettr API发起请求，然后将结果返回给AI客户端，最终呈现给你。

这个架构的精妙之处在于 解耦 ：Lettr团队只需维护一个遵循MCP标准的Server，就能让所有支持MCP的AI客户端获得邮件操作能力，无需每个AI客户端都去单独集成Lettr API。

2.2 Lettr邮件服务：现代、开发者友好的邮件API

为什么是Lettr，而不是其他邮件服务？从开发者的视角看，Lettr的设计抓住了几个痛点：

• 清晰的REST API ：API设计直观，文档完备，减少了集成时的猜测成本。
• 强大的模板引擎 ：支持带有逻辑判断、循环的模板语言，以及 {{variable}} 形式的合并标签，让动态邮件内容生成变得简单。
• 开箱即用的送达率优化 ：事务性邮件的核心是“必达”。Lettr内置了SPF、DKIM、DMARC等发件人认证机制的引导配置，并管理发信IP声誉，这是自建邮件服务器或使用普通SMTP服务最头疼的地方。
• Webhook事件通知 ：邮件是否被打开、链接是否被点击、是否被退回，这些事件可以通过Webhook实时回推到你的服务器，便于构建用户交互追踪系统。

Lettr MCP Server本质上就是这个强大API的“自然语言交互层”。它将API的端点映射为AI可以理解和调用的“工具”，你无需记忆具体的API路径、HTTP方法和请求体格式，用自然语言描述你的目标即可。

3. 从零开始：详细配置与实操指南

理论说得再多，不如动手配置一遍。下面我将以最常用的 Claude Desktop 和 Cursor 为例，带你完成从注册Lettr到在AI助手中成功发送第一封邮件的全过程。

3.1 前期准备：获取Lettr API密钥

1. 注册账号 ：访问 Lettr官网 ，使用邮箱注册一个免费账户。免费额度通常足够日常开发测试使用。
2. 验证域名 ：这是关键且不可跳过的一步。在Lettr控制台的“Domains”页面，添加你的发件域名（例如 mail.yourdomain.com ）。添加后，Lettr会生成一组DNS记录（TXT记录用于SPF和DKIM）。你需要到你的域名注册商或DNS服务商（如Cloudflare、阿里云）处，添加这些记录。验证过程通常需要几分钟到几小时。 务必完成此步骤 ，否则无法向Gmail、Outlook等主流邮箱服务商发信。
3. 创建API密钥 ：在控制台的“API Keys”页面，创建一个新的密钥。它会以 lttr_ 开头。请立即复制并妥善保存，因为它只显示一次。

3.2 配置 Claude Desktop

Claude Desktop 是Anthropic官方的桌面客户端，对MCP的支持非常原生。

1. 打开Claude Desktop，点击左下角的设置图标，进入设置菜单。
2. 在设置侧边栏，找到并点击 “开发者” 选项卡。
3. 你会看到一个名为 “编辑配置” 的按钮，点击它。这会打开一个名为 claude_desktop_config.json 的JSON配置文件。
4. 在配置文件中，你需要添加 mcpServers 字段。如果你的文件是空的或没有该字段，可以粘贴以下完整配置。如果已有其他MCP服务器，只需在 mcpServers 对象内新增一个 lettr 节点。

{
  "mcpServers": {
    "lettr": {
      "command": "npx",
      "args": ["-y", "lettr-mcp"],
      "env": {
        "LETTR_API_KEY": "lttr_你的实际API密钥",
        "SENDER_EMAIL_ADDRESS": "noreply@your-verified-domain.com"
      }
    }
  }
}

配置参数详解 ：

• command: "npx" : 告诉Claude Desktop使用 npx 命令来运行工具。 npx 会自动下载并执行npm包，无需你本地全局安装 lettr-mcp 。
• args: ["-y", "lettr-mcp"] : -y 参数表示对任何提示都自动回答“yes”， lettr-mcp 是要执行的npm包名。
• env : 设置环境变量。这里必须提供 LETTR_API_KEY 。强烈建议同时设置 SENDER_EMAIL_ADDRESS 为一个你已验证域名的邮箱地址，这样在发送邮件时就不需要每次都指定发件人了。

5. 保存配置文件并完全重启Claude Desktop。重启后，Claude就具备了邮件超能力。

3.3 配置 Cursor

Cursor 作为一款AI优先的IDE，其MCP配置方式与Claude Desktop类似，但入口在编辑器内部。

1. 在Cursor中，使用快捷键 Cmd/Ctrl + Shift + P 打开命令面板。
2. 输入并选择 “Cursor Settings: Open Settings UI” 。
3. 在设置界面的搜索框中，输入 “MCP” 。
4. 你会找到 “MCP Servers” 相关的设置项。通常，你需要点击 “Add new global MCP server” 。
5. 这会引导你编辑一个全局配置文件（如 ~/.cursor/mcp.json ），其内容格式与Claude Desktop的完全一致。将上述同样的JSON配置粘贴进去即可。
6. 保存文件，并重启Cursor。

注意 ：无论是Claude Desktop还是Cursor，修改MCP配置后 必须重启应用 ，新的服务器连接才会被建立。你可以通过向AI助手提问“你有什么工具？”或“你能发邮件吗？”，来测试连接是否成功。如果配置正确，AI会列出 send-email 等工具。

4. 核心工具详解与实战应用

配置完成后，我们来看看这些工具在实战中如何大显身手。以下对话示例基于Claude，但原理在Cursor中通用。

4.1 邮件发送：从简单到复杂

场景一：发送一封简单的纯文本邮件 你只需要告诉AI你的意图。

• 你的指令 ：“给 test@example.com 发封邮件，主题是‘测试邮件’，内容就写‘这是一封来自MCP的测试邮件。’”
• AI的理解与操作 ：AI识别出这是 send-email 工具的适用场景。它会向你确认发件人（如果你在配置中设置了默认发件人，则跳过此步），然后构造请求。底层上，MCP Server会向Lettr API发起一个POST请求到 /v1/emails 端点。
• 实操心得 ：第一次测试时，建议先发给自己。同时，检查垃圾邮件箱。如果邮件进了垃圾箱，通常是域名DNS记录（SPF/DKIM）未正确设置或未生效，请回到Lettr控制台检查域名验证状态。

场景二：使用HTML模板和合并标签发送个性化邮件 这才是事务性邮件的常态。假设你已在Lettr后台创建了一个名为 order_shipped 的模板，内容包含HTML，并使用 {{order_id}} 和 {{tracking_link}} 作为变量。

• 你的指令 ：“使用模板 order_shipped 给客户 customer@domain.com 发送一封订单已发货的通知邮件，订单号是 #12345 ，物流跟踪链接是 https://example.com/track/12345 。”
• AI的操作 ：AI会调用 send-email 工具，并填充 template_id 和 merge_tags 参数。 merge_tags 是一个JSON对象，如 {"order_id": "#12345", "tracking_link": "https://..."} 。Lettr服务器会在发送前，将模板中的变量替换为实际值。
• 注意事项 ：确保模板中定义的合并标签名称与你提供的键名完全一致，包括大小写。在让AI发送重要通知前，最好先用一个测试模板和测试邮箱验证一下替换效果。

4.2 模板管理：无需离开编辑器

你可以在对话中直接管理所有模板，效率提升惊人。

• 列出模板 ：问一句“我现在有哪些邮件模板？”，AI会调用 list-templates 工具，返回一个包含模板ID、名称、创建时间的清晰列表。
• 查看模板详情 ：“我想看看‘welcome_email’这个模板的详细内容和用了哪些变量。” AI会依次调用 get-template （获取HTML内容）和 get-merge-tags 工具，将模板源码和所需的变量列表呈现给你。
• 创建新模板 ：你可以直接口述需求。“创建一个新的模板，名字叫‘password_reset’，主题是‘重置您的密码’，HTML内容就用这个： <h1>您好 {{name}}</h1><p>请点击<a href='{{reset_link}}'>此链接</a>重置密码。</p> ” AI会调用 create-template 工具完成创建。更复杂的模板，你也可以先在Lettr的可视化编辑器里设计好，然后在这里获取其ID使用。

4.3 域名与Webhook监控

• 检查域名状态 ：在配置初期或遇到发信问题时，可以问：“我验证的域名状态怎么样了？” AI通过 list-domains 工具返回结果，你会看到每个域名的验证状态（verified/pending）和相关的DNS记录信息，方便你排查配置问题。
• 查看Webhook事件 ：如果你配置了Webhook来接收邮件事件，可以随时让AI检查最近的状态。“最近有什么webhook事件送达失败吗？” AI通过 list-webhooks 和 get-webhook 工具，可以告诉你Webhook的配置详情和最近的送达日志，对于调试回调接口非常有用。

5. 高级技巧与避坑指南

经过一段时间的深度使用，我总结了一些能让体验更顺畅的技巧和常见的“坑”。

5.1 环境变量与默认参数的妙用

在配置文件中设置 SENDER_EMAIL_ADDRESS 和 REPLY_TO_EMAIL_ADDRESS 环境变量是 最佳实践 。这能避免每次发邮件时的重复确认。如果你有多个项目或环境（开发、测试、生产），可以考虑使用不同的配置文件或通过脚本动态设置环境变量。

你也可以在运行MCP Server时通过命令行参数直接指定，例如在本地测试时：

npx -y lettr-mcp --key lttr_你的密钥 --sender noreply@dev.example.com

这种方式更灵活，但不如写入配置文件方便持久化。

5.2 本地开发与调试

项目仓库提供了完整的本地开发指南。如果你想贡献代码或深度定制，可以：

1. git clone 项目到本地。
2. 使用 pnpm install 安装依赖（项目使用 pnpm 作为包管理器，用 npm 或 yarn 可能需要调整）。
3. 运行 pnpm run build 编译TypeScript代码。
4. 在MCP客户端配置中，将 command 改为 node ， args 指向你本地编译好的 dist/index.js 的绝对路径。

这对于调试工具调用逻辑、添加新功能或理解MCP Server内部工作原理至关重要。

一个常见的坑是路径问题 ：在配置本地路径时，Windows用户要特别注意反斜杠转义或使用正斜杠，最好使用绝对路径。例如： "args": ["C:/Projects/lettr-mcp/dist/index.js"] 。

5.3 错误处理与排查

当AI助手返回一个错误时，信息可能比较概括。你需要学会解读：

1. “Tool call failed” 或 “Server error” ：这通常是MCP Server进程本身启动失败或崩溃。首先检查你的配置文件JSON格式是否正确，没有缺少逗号或括号。然后检查 LETTR_API_KEY 环境变量是否设置正确，密钥是否有效。
2. “Invalid API key” ：显然是API密钥错误或已失效。去Lettr后台重新生成一个。
3. “Sender domain not verified” ：发件人邮箱的域名没有通过验证。请确认你在Lettr控制台添加并正确配置了该域名的DNS记录，且状态显示为“Verified”。DNS更改全球生效可能需要时间。
4. “Template not found” ：你提供的模板ID或名称不对。先用 list-templates 工具确认准确的模板ID。

排查黄金步骤 ：遇到问题，首先回到最基本的命令行测试。打开终端，设置好环境变量，直接运行 npx -y lettr-mcp ，看看Server能否正常启动而不报错。这能隔离IDE或AI客户端带来的复杂因素。

5.4 安全须知

• API密钥即密码 ：你的 LETTR_API_KEY 拥有发送邮件、管理模板和域名的全部权限。切勿将它提交到公开的代码仓库（如GitHub）。配置文件 claude_desktop_config.json 或 mcp.json 是本地文件，相对安全，但也要确保其存放目录的隐私性。
• 最小权限原则 ：虽然Lettr目前可能只提供一种全权限密钥，但在意识上要将其视为敏感信息。如果是在团队共享的电脑上配置，需格外谨慎。

将Lettr MCP Server集成到你的AI编程工作流中，初期可能需要一点配置成本，但一旦跑通，它带来的效率提升是线性的。它把邮件从一种需要“额外处理”的外部服务，变成了编码过程中可以自然对话、即时调用的内部能力。这种“一切皆可对话，一切皆可操作”的体验，或许正是未来开发者工具演进的一个方向。我现在已经习惯了在构思功能时，直接让AI助手处理相关的邮件逻辑，感觉就像身边多了一个随时待命的邮件运维专家。