基于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协议的核心思想是解耦与标准化。它定义了三种核心资源Tools工具服务器可以向客户端声明一系列可调用的函数。例如lettr-mcp可能声明一个search_emails的工具。Resources资源服务器可以暴露一系列可通过URI访问的只读数据。例如一个邮件可以被定义为resource://lettr/emails/{emailId}。Prompts提示词模板服务器可以提供一些预定义的提示词模板客户端可以填充变量后使用。lettr-mcp选择实现MCP协议是一个极具前瞻性的决策。这意味着对开发者友好任何支持MCP的客户端名单正在快速增长都能立即接入lettr-mcp无需为每个客户端单独开发适配器。关注点分离lettr-mcp团队可以专注于做好邮件API的集成、数据解析和安全性而不用操心每个前端应用怎么调用它。生态优势它直接进入了正在蓬勃发展的MCP生态潜在用户和影响力远大于一个独立的、封闭的邮件工具库。2.2 lettr-mcp 的架构设计拆解从项目代码结构来看lettr-mcp采用了典型的Node.js服务架构其核心模块划分清晰协议层MCP Server Core基于modelcontextprotocol/sdk官方SDK构建MCP服务器骨架。这一层负责与MCP客户端建立连接通过stdio或SSE注册工具Tools和资源Resources并处理来自客户端的JSON-RPC请求。服务抽象层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等接口。数据转换与工具层将从邮件API获取的原始、复杂的JSON数据转换为LLM易于理解和处理的简洁格式例如提取发件人、主题、正文纯文本部分、日期等。同时将常见的邮件操作封装成MCP Tools例如list_emails: 列出收件箱邮件支持分页、筛选。get_email: 获取特定邮件的完整内容和元数据。search_emails: 根据关键词搜索邮件。可能还有send_email,delete_email等写操作工具需谨慎设计权限。配置与凭证管理如何安全地存储和使用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为例这是最具挑战性的一步但流程是标准的创建Google Cloud项目在控制台新建一个项目或选择一个现有项目。启用Gmail API在“API和服务” - “库”中搜索并启用“Gmail API”。配置OAuth同意屏幕选择用户类型通常先选“外部”用于测试。填写应用名称如“My AI Mail Assistant”、用户支持邮箱、开发者联系信息。在“范围”部分添加https://www.googleapis.com/auth/gmail.readonly范围如果只需要读权限。务必只申请最小必要权限。添加测试用户你自己的Google账号。创建凭证在“凭证”页面点击“创建凭证” - “OAuth 客户端ID”。应用类型选择“桌面应用”。创建后你会获得客户端IDClient ID和客户端密钥Client Secret。下载JSON文件或妥善保存。获取刷新令牌Refresh Tokenlettr-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。复制并编辑配置文件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: ... } }安装依赖并测试运行npm install npm start # 或 node src/index.js如果配置正确服务应该启动并等待MCP客户端的连接通常通过标准输入输出stdio。配置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环境变量用于传递配置文件路径。重启Claude Desktop完全退出并重新启动Claude Desktop。启动后在聊天界面你应该能看到新的工具图标或者直接尝试询问Claude“你能看到我的最新邮件吗” Claude应该会调用lettr-mcp的工具来获取邮件信息。4. 核心功能实现与工具调用剖析当MCP客户端如Claude与lettr-mcp服务器成功握手后客户端会获知服务器提供了哪些工具Tools。我们来看看这些工具是如何被设计和使用的。4.1 邮件列表工具 (list_emails)这是最常用的工具。其内部实现大致如下参数设计它很可能接受maxResults返回数量如10、label标签如INBOX、pageToken用于分页等参数。这直接映射到Gmail API的users.messages.list参数。API调用lettr-mcp使用配置的刷新令牌向Google的令牌端点请求一个新的访问令牌。然后用这个访问令牌调用Gmail API。数据简化Gmail API返回的邮件列表只包含邮件ID和线程ID等元数据。list_emails工具可能不会一次性获取所有邮件的完整内容那会很慢而是先返回一个包含邮件ID、主题、发件人、日期和片段snippet的列表。分页处理如果邮件很多工具会处理分页逻辑可能将nextPageToken返回给客户端客户端可以在下次调用时传入以实现“加载更多”。在Claude中的对话示例你 “帮我看看收件箱最近5封邮件的主题。”Claude内部调用list_emails工具参数maxResults: 5, label: INBOXClaude “好的这是你收件箱最新的5封邮件1. [会议邀请] 项目复盘会 - 来自张三2. 您的月度账单已就绪 - 来自某服务商...”4.2 邮件详情工具 (get_email)当用户或AI对某封邮件感兴趣时需要获取其完整内容。参数设计主要参数是emailId邮件唯一标识。内容解析这是技术难点。Gmail API返回的邮件原始数据是RFC 2822格式的MIME邮件字符串或者是一个结构化的payload。一封邮件可能包含多个部分multipart/mixed, multipart/alternative。纯文本text/plain和HTMLtext/html版本。内嵌图片Content-ID引用和附件。转换策略lettr-mcp需要从这复杂的MIME树中提取出最核心、对LLM最友好的文本内容。通常的策略是优先提取text/plain部分因为这是最干净的文本。如果没有纯文本部分则提取text/html部分并使用一个简单的库如html-to-text将其转换为纯文本去除所有标签、样式。明智地处理附件可能只提及附件的文件名和类型或者对于文本类附件.txt, .pdf需OCR进行提取。这需要权衡性能和实用性。返回结构工具会返回一个结构化的对象包含id,threadId,subject,from,to,date,body提取后的纯文本以及attachments附件列表。注意事项邮件正文转换的保真度很重要。复杂的HTML邮件如营销邮件转换后可能丢失重要布局信息或包含无关的链接文本。lettr-mcp可能需要一些启发式规则来清理“退订”、“查看网页版”等垃圾文本。4.3 搜索工具 (search_emails)这可能是最有用的工具它直接将Gmail强大的搜索语法暴露给了LLM。参数传递核心参数是query搜索查询字符串。LLM可以将用户的自然语言转换为Gmail搜索语法。用户说“找上个月来自老板的关于预算的邮件。”LLM可以构造查询from:bosscompany.com budget after:2024/03/01 before:2024/04/01。实现这个工具底层同样是调用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授权失败与令牌失效问题运行授权脚本时浏览器返回“错误 400redirect_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服务器。排查步骤检查路径确认Claude配置文件中command和args的路径是绝对路径并且指向正确的文件。Node.js的路径尤其容易出错。手动测试服务器在终端直接运行node /path/to/index.js看服务是否能正常启动有无报错如配置文件读取失败、凭证错误。这能隔离是否是lettr-mcp本身的问题。检查Claude Desktop日志Claude Desktop通常会有更详细的日志文件里面会记录加载MCP服务器时的错误信息。根据日志查找原因。检查权限确保Claude Desktop有权限执行Node.js命令和读取相关文件。6.3 邮件内容解析异常问题AI返回的邮件正文是乱码或者包含了大量无关的HTML标签和JavaScript代码。原因lettr-mcp的HTML到文本转换逻辑可能不够健壮或者遇到了特殊编码的邮件。排查可以尝试在get_email工具的实现中增加更强大的HTML清理库如sanitize-html配合html-to-text。对于编码问题需要确保在解析MIME部分时正确检测和处理charset如utf-8,gb2312。一个实用的调试方法是在代码中临时将原始邮件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服务器这可能会让你的智能体变得更加强大和灵活。