基于MCP协议构建LLM邮件助手：lettr-mcp项目实战与安全配置指南

1. 项目概述：一个为LLM开启“读信”能力的MCP服务器

如果你正在开发一个基于大语言模型（LLM）的智能体，并且希望它能帮你处理电子邮件，比如自动分类、总结、回复，或者从收件箱里提取特定信息，那么你很可能需要让LLM能够“读取”你的邮件。然而，直接让LLM访问你的邮箱，不仅涉及复杂的OAuth授权、API调用，更关乎敏感数据的安全与隐私。这就是lettr-com/lettr-mcp这个项目诞生的背景。

简单来说，lettr-mcp是一个实现了Model Context Protocol (MCP)标准的服务器。你可以把它理解为一个“邮箱连接器”或“邮件数据桥”。它的核心职责是，以一种标准化、安全可控的方式，将你的电子邮件数据（目前主要支持Gmail和Outlook）暴露给你正在使用的LLM应用或框架（例如 Claude Desktop, Cursor, Windsurf，或是任何集成了MCP客户端的工具）。有了它，你的AI助手就不再是“盲人”，它能安全地“看到”并处理你的邮件内容，从而为你提供更强大的邮件管理自动化能力。

这个项目由 LettR 团队开源，其价值在于将复杂的邮件服务API封装成了一个轻量、协议化的工具。对于开发者而言，你无需从零开始研究Gmail API的OAuth 2.0流程、邮件格式解析（MIME）和增量同步逻辑；对于最终用户，它提供了一种相对安全的方式，在用户明确授权和本地运行的前提下，让AI工具有限度地访问邮件数据。接下来，我将深入拆解这个项目的设计思路、核心实现、配置细节以及在实际使用中可能遇到的“坑”。

2. 核心架构与MCP协议解析

2.1 什么是MCP？为什么是它？

Model Context Protocol (MCP) 是由 Anthropic 提出并推动的一个开放协议。它的目标是为LLM应用（客户端）和各种数据源、工具（服务器）建立一个统一的“对话”标准。在MCP出现之前，每个AI应用（如某个IDE插件）如果想接入一个新的数据源（如Notion、Jira、邮箱），都需要自己实现一套特定的集成代码，这导致了大量的重复劳动和生态碎片化。

MCP协议的核心思想是解耦与标准化。它定义了三种核心资源：

1. Tools（工具）：服务器可以向客户端声明一系列可调用的函数。例如，lettr-mcp可能声明一个search_emails的工具。
2. Resources（资源）：服务器可以暴露一系列可通过URI访问的只读数据。例如，一个邮件可以被定义为resource://lettr/emails/{emailId}。
3. Prompts（提示词模板）：服务器可以提供一些预定义的提示词模板，客户端可以填充变量后使用。

lettr-mcp选择实现MCP协议，是一个极具前瞻性的决策。这意味着：

• 对开发者友好：任何支持MCP的客户端（名单正在快速增长）都能立即接入lettr-mcp，无需为每个客户端单独开发适配器。
• 关注点分离：lettr-mcp团队可以专注于做好邮件API的集成、数据解析和安全性，而不用操心每个前端应用怎么调用它。
• 生态优势：它直接进入了正在蓬勃发展的MCP生态，潜在用户和影响力远大于一个独立的、封闭的邮件工具库。

2.2 lettr-mcp 的架构设计拆解

从项目代码结构来看，lettr-mcp采用了典型的Node.js服务架构，其核心模块划分清晰：

1. 协议层（MCP Server Core）：基于@modelcontextprotocol/sdk官方SDK，构建MCP服务器骨架。这一层负责与MCP客户端建立连接（通过stdio或SSE），注册工具（Tools）和资源（Resources），并处理来自客户端的JSON-RPC请求。
2. 服务抽象层（Email Providers）：这是项目的核心业务逻辑所在。它抽象出了统一的邮件服务接口（如EmailProvider），然后为不同的邮件服务商（目前是Gmail和Outlook）提供具体实现（GmailProvider,OutlookProvider）。
   • Gmail实现：通过Google的Gmail API v1进行交互。难点在于处理OAuth 2.0授权流（需要客户端ID和密钥，生成刷新令牌），以及高效地使用users.messages.list和users.messages.getAPI来获取和解析邮件。
   • Outlook实现：通过Microsoft Graph API进行交互。同样需要处理OAuth 2.0授权（MSAL库），调用诸如/me/messages等接口。
3. 数据转换与工具层：将从邮件API获取的原始、复杂的JSON数据，转换为LLM易于理解和处理的简洁格式（例如，提取发件人、主题、正文纯文本部分、日期等）。同时，将常见的邮件操作封装成MCP Tools，例如：
   • list_emails: 列出收件箱邮件（支持分页、筛选）。
   • get_email: 获取特定邮件的完整内容和元数据。
   • search_emails: 根据关键词搜索邮件。
   • （可能还有）send_email,delete_email等写操作工具（需谨慎设计权限）。
4. 配置与凭证管理：如何安全地存储和使用OAuth凭证（client_id,client_secret,refresh_token）是此类项目的关键。lettr-mcp通常要求用户通过环境变量或配置文件提供这些信息，并且所有通信建议在本地进行，避免凭证泄露。

注意：将OAuth刷新令牌（refresh token）视为最高机密。它代表了长期的访问权限。lettr-mcp作为本地运行的服务，相比云端服务，降低了令牌被中间人攻击的风险，但你仍需确保运行环境的安全。

3. 从零开始配置与运行 lettr-mcp

理论讲完，我们进入实战环节。假设你是一名开发者，想在 Claude Desktop 中启用邮件读取功能，以下是详细的步骤。

3.1 前置条件与环境准备

首先，你需要准备好以下“食材”：

• Node.js 环境：建议使用LTS版本（如18.x或20.x）。这是运行lettr-mcp的基础。
• 一个代码仓库：将lettr-com/lettr-mcp项目克隆到本地。
• 邮件服务商开发者账号：以Gmail为例，你需要访问 Google Cloud Console 创建一个项目并启用Gmail API。

3.2 获取OAuth 2.0凭证（以Gmail为例）

这是最具挑战性的一步，但流程是标准的：

1. 创建Google Cloud项目：在控制台新建一个项目，或选择一个现有项目。
2. 启用Gmail API：在“API和服务” -> “库”中，搜索并启用“Gmail API”。
3. 配置OAuth同意屏幕：
   • 选择用户类型（通常先选“外部”用于测试）。
   • 填写应用名称（如“My AI Mail Assistant”）、用户支持邮箱、开发者联系信息。
   • 在“范围”部分，添加https://www.googleapis.com/auth/gmail.readonly范围（如果只需要读权限）。务必只申请最小必要权限。
   • 添加测试用户（你自己的Google账号）。
4. 创建凭证：
   • 在“凭证”页面，点击“创建凭证” -> “OAuth 客户端ID”。
   • 应用类型选择“桌面应用”。
   • 创建后，你会获得客户端ID（Client ID）和客户端密钥（Client Secret）。下载JSON文件或妥善保存。
5. 获取刷新令牌（Refresh Token）：
   • lettr-mcp通常提供一个授权脚本或指引。你需要用上一步的Client ID和Secret，构造一个OAuth URL，在浏览器中访问并授权，从而换取一个授权码（Authorization Code）。
   • 然后，再用这个授权码向Google的令牌端点发起请求，交换得到访问令牌（Access Token）和刷新令牌（Refresh Token）。
   • 访问令牌有效期短（约1小时），而刷新令牌是长期有效的，lettr-mcp会用它来自动获取新的访问令牌。这个刷新令牌就是你最终需要配置到lettr-mcp中的核心凭证。

实操心得：很多人在获取刷新令牌这一步卡住，因为Google的OAuth流程对“桌面应用”有严格限制。一个更简单的方法是使用一些成熟的OAuth2.0命令行工具（如oauth2l）或者参考其他开源邮件客户端项目的授权流程。lettr-mcp的文档或代码示例中应该会提供具体的授权脚本（例如一个auth.js文件），运行它并跟随指引操作是最稳妥的。

3.3 配置MCP客户端（以Claude Desktop为例）

假设你已经成功获取了Gmail的刷新令牌，并假设lettr-mcp项目根目录下有一个示例配置文件config.example.json。

1. 复制并编辑配置文件：

   cp config.example.json config.json

   编辑config.json，填入你的凭证：

   { "gmail": { "clientId": "YOUR_CLIENT_ID.apps.googleusercontent.com", "clientSecret": "YOUR_CLIENT_SECRET", "refreshToken": "YOUR_LONG_REFRESH_TOKEN" }, // 如果有Outlook配置，也放在这里 "outlook": { "clientId": "...", "tenantId": "...", "clientSecret": "...", "refreshToken": "..." } }

2. 安装依赖并测试运行：

   npm install npm start # 或 node src/index.js

   如果配置正确，服务应该启动，并等待MCP客户端的连接（通常通过标准输入输出stdio）。

3. 配置Claude Desktop：

   • 找到Claude Desktop的MCP配置文件。在macOS上，通常位于~/Library/Application Support/Claude/claude_desktop_config.json。在Windows上，可能在%APPDATA%\Claude\claude_desktop_config.json。
   • 编辑该文件，添加lettr-mcp服务器配置：

   { "mcpServers": { "lettr": { "command": "node", "args": [ "/ABSOLUTE/PATH/TO/YOUR/lettr-mcp/src/index.js" ], "env": { "CONFIG_PATH": "/ABSOLUTE/PATH/TO/YOUR/lettr-mcp/config.json" } } } }

   • 关键点：command和args必须指向你本地lettr-mcp项目的入口文件。env环境变量用于传递配置文件路径。

4. 重启Claude Desktop：完全退出并重新启动Claude Desktop。启动后，在聊天界面，你应该能看到新的工具图标，或者直接尝试询问Claude：“你能看到我的最新邮件吗？” Claude应该会调用lettr-mcp的工具来获取邮件信息。

4. 核心功能实现与工具调用剖析

当MCP客户端（如Claude）与lettr-mcp服务器成功握手后，客户端会获知服务器提供了哪些工具（Tools）。我们来看看这些工具是如何被设计和使用的。

4.1 邮件列表工具 (list_emails)

这是最常用的工具。其内部实现大致如下：

1. 参数设计：它很可能接受maxResults（返回数量，如10）、label（标签，如INBOX）、pageToken（用于分页）等参数。这直接映射到Gmail API的users.messages.list参数。
2. API调用：lettr-mcp使用配置的刷新令牌，向Google的令牌端点请求一个新的访问令牌。然后用这个访问令牌，调用Gmail API。
3. 数据简化：Gmail API返回的邮件列表只包含邮件ID和线程ID等元数据。list_emails工具可能不会一次性获取所有邮件的完整内容（那会很慢），而是先返回一个包含邮件ID、主题、发件人、日期和片段（snippet）的列表。
4. 分页处理：如果邮件很多，工具会处理分页逻辑，可能将nextPageToken返回给客户端，客户端可以在下次调用时传入以实现“加载更多”。

在Claude中的对话示例：

你： “帮我看看收件箱最近5封邮件的主题。”Claude：（内部调用list_emails工具，参数maxResults: 5, label: 'INBOX'）Claude： “好的，这是你收件箱最新的5封邮件：1. [会议邀请] 项目复盘会 - 来自张三；2. 您的月度账单已就绪 - 来自某服务商；...”

4.2 邮件详情工具 (get_email)

当用户或AI对某封邮件感兴趣时，需要获取其完整内容。

1. 参数设计：主要参数是emailId（邮件唯一标识）。
2. 内容解析：这是技术难点。Gmail API返回的邮件原始数据是RFC 2822格式的MIME邮件字符串，或者是一个结构化的payload。一封邮件可能包含：
   • 多个部分（multipart/mixed, multipart/alternative）。
   • 纯文本（text/plain）和HTML（text/html）版本。
   • 内嵌图片（Content-ID引用）和附件。
3. 转换策略：lettr-mcp需要从这复杂的MIME树中，提取出最核心、对LLM最友好的文本内容。通常的策略是：
   • 优先提取text/plain部分，因为这是最干净的文本。
   • 如果没有纯文本部分，则提取text/html部分，并使用一个简单的库（如html-to-text）将其转换为纯文本，去除所有标签、样式。
   • 明智地处理附件：可能只提及附件的文件名和类型，或者对于文本类附件（.txt, .pdf需OCR）进行提取。这需要权衡性能和实用性。
4. 返回结构：工具会返回一个结构化的对象，包含：id,threadId,subject,from,to,date,body（提取后的纯文本），以及attachments（附件列表）。

注意事项：邮件正文转换的保真度很重要。复杂的HTML邮件（如营销邮件）转换后可能丢失重要布局信息或包含无关的链接文本。lettr-mcp可能需要一些启发式规则来清理“退订”、“查看网页版”等垃圾文本。

4.3 搜索工具 (search_emails)

这可能是最有用的工具，它直接将Gmail强大的搜索语法暴露给了LLM。

1. 参数传递：核心参数是query（搜索查询字符串）。LLM可以将用户的自然语言转换为Gmail搜索语法。
   • 用户说：“找上个月来自老板的关于预算的邮件。”
   • LLM可以构造查询：from:boss@company.com budget after:2024/03/01 before:2024/04/01。
2. 实现：这个工具底层同样是调用users.messages.listAPI，只是将q参数设置为构造好的搜索查询。后续的数据获取和简化流程与list_emails类似。

能力边界：LLM并不直接“理解”你的邮箱结构，它只是学会了如何调用这些工具。真正的搜索逻辑是由Gmail的服务器执行的。lettr-mcp的作用是提供了一个安全、标准的通道。

5. 安全、隐私考量与最佳实践

让AI访问邮件，安全是头等大事。lettr-mcp的本地运行模式是其主要安全优势，但仍有多个层面需要考虑。

5.1 运行模式安全

• 本地即安全：lettr-mcp作为本地进程运行，你的邮件数据（包括OAuth令牌）永远不会离开你的电脑。这与将令牌交给某个云端AI服务有本质区别。
• 网络隔离：确保该服务只通过MCP协议与本地客户端（如Claude Desktop）通信，不对外开放任何网络端口。

5.2 OAuth权限最小化

在配置Google Cloud OAuth时，务必坚持最小权限原则：

• 仅读权限：对于大多数AI助手场景，https://www.googleapis.com/auth/gmail.readonly范围已经足够。这允许AI读取邮件元数据和内容，但不能发送、删除或修改邮件。
• 谨慎授予写权限：除非你明确需要AI代发邮件，否则不要申请https://www.googleapis.com/auth/gmail.modify或https://mail.google.com/等更宽泛的范围。发送邮件功能 (send_email工具) 如果实现，必须包含二次确认机制。

5.3 配置与凭证管理

• 配置文件安全：config.json包含了你的客户端密钥和刷新令牌。务必将其排除在版本控制系统（如Git）之外。.gitignore文件中必须添加config.json。
• 环境变量替代：更安全的方式是使用环境变量而非配置文件。你可以在启动命令或系统配置中设置GMAIL_CLIENT_ID、GMAIL_REFRESH_TOKEN等，然后在代码中通过process.env读取。
• 定期审计：定期访问Google Cloud Console的“OAuth 2.0 同意屏幕”和“凭证”页面，查看有哪些应用拥有你账户的访问权限，移除不再使用的授权。

5.4 对LLM的提示词约束

即使工具层面是安全的，也需要在AI的“头脑”里设置边界。在集成lettr-mcp的系统中，应该在系统提示词（System Prompt）中加入明确的约束：

• “你只能访问用户明确要求你查看的邮件。”
• “未经用户二次确认，你不得执行发送、转发或删除邮件的操作（如果未来有此功能）。”
• “处理邮件内容时，需注意用户隐私，不得在回复中泄露其他无关邮件的敏感信息。”

6. 常见问题与故障排查实录

在实际部署和使用lettr-mcp的过程中，你几乎一定会遇到下面这些问题。这里记录了我的踩坑实录和解决方案。

6.1 OAuth授权失败与令牌失效

• 问题：运行授权脚本时，浏览器返回“错误 400：redirect_uri_mismatch”。

• 原因：在Google Cloud Console创建OAuth客户端ID时，你必须在“已授权的重定向URI”中精确添加授权脚本使用的重定向URI。对于本地桌面应用，通常是http://localhost:端口号或urn:ietf:wg:oauth:2.0:oob。

• 解决：仔细检查授权脚本期望的URI，并确保在Google控制台中已正确添加。

• 问题：服务运行一段时间后，突然无法获取邮件，日志显示“invalid_grant”或“Token has been expired or revoked”。

• 原因1：刷新令牌可能已失效。如果用户在Google账户安全设置中撤销了应用的访问权限，或者令牌长时间未使用，都可能失效。

• 解决1：需要重新走一遍授权流程，获取新的刷新令牌。

• 原因2：服务器时间不同步。进行令牌验证时，如果本地系统时间与NTP服务器偏差过大，可能导致令牌被判定为无效。

• 解决2：同步你的系统时间。

6.2 MCP客户端连接失败

• 问题：Claude Desktop重启后，没有发现邮件工具，或日志显示无法连接到MCP服务器。
• 排查步骤：
  1. 检查路径：确认Claude配置文件中command和args的路径是绝对路径，并且指向正确的文件。Node.js的路径尤其容易出错。
  2. 手动测试服务器：在终端直接运行node /path/to/index.js，看服务是否能正常启动，有无报错（如配置文件读取失败、凭证错误）。这能隔离是否是lettr-mcp本身的问题。
  3. 检查Claude Desktop日志：Claude Desktop通常会有更详细的日志文件，里面会记录加载MCP服务器时的错误信息。根据日志查找原因。
  4. 检查权限：确保Claude Desktop有权限执行Node.js命令和读取相关文件。

6.3 邮件内容解析异常

• 问题：AI返回的邮件正文是乱码，或者包含了大量无关的HTML标签和JavaScript代码。
• 原因：lettr-mcp的HTML到文本转换逻辑可能不够健壮，或者遇到了特殊编码的邮件。
• 排查：
  1. 可以尝试在get_email工具的实现中，增加更强大的HTML清理库，如sanitize-html配合html-to-text。
  2. 对于编码问题，需要确保在解析MIME部分时正确检测和处理charset（如utf-8,gb2312）。
  3. 一个实用的调试方法是：在代码中临时将原始邮件MIME数据或解析后的内容打印到日志文件，对比查看问题出在哪个环节。

6.4 性能问题：获取邮件列表缓慢

• 问题：让AI列出最近10封邮件，等待时间超过10秒。
• 原因：list_emails工具可能为了返回更丰富的信息，在获取邮件ID列表后，又同步地逐一调用了get_email来获取每封邮件的片段（snippet），导致API调用次数暴增。
• 优化：
  • Gmail API的users.messages.list本身就可以通过fields参数请求返回部分数据，如messages(id, threadId, snippet)。应优先使用这个接口，避免不必要的get调用。
  • 实现异步并发控制。如果需要获取多封邮件的更多详情，可以使用Promise.all等并发操作，但要注意Gmail API可能有速率限制。
  • 在工具层面提供更细粒度的参数，比如includeSnippet: true和includeFullBody: false，让客户端根据需要决定获取数据的深度。

最后，我想分享一点个人体会。lettr-mcp这类项目代表了AI应用开发的一个趋势：将核心能力（LLM）与外部数据和工具（通过MCP）解耦。作为开发者，我们的工作重心从“如何让AI理解某个API”变成了“如何为AI设计一套好用、安全、标准的工具接口”。在配置过程中，最繁琐的永远是OAuth和环境配置，但一旦打通，你会发现为AI赋能一种新感官（如“视觉”读邮件、“听觉”读日历）变得如此标准化。如果你正在构建复杂的AI智能体，不妨以lettr-mcp为参考，思考如何将你的业务能力也封装成MCP服务器，这可能会让你的智能体变得更加强大和灵活。