Klavis 开源仓库 Outlook MCP 服务器实战：基于 Microsoft Graph API 的邮件工具集成指南

Klavis 开源仓库 Outlook MCP 服务器实战基于 Microsoft Graph API 的邮件工具集成指南【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本指南以 mcp_servers/outlook/README.md 为核心文档系统讲解该 MCP 服务器如何通过 Microsoft Graph API 将 Outlook 邮件能力文件夹管理、邮件读写、草稿全生命周期、转发/回复、移动归档开放给 AI Agent。读完本文你将掌握 16 个 MCP 工具的完整参数约定、底层 Graph API 调用链与认证机制并能直接部署、接入并扩展这个模块。模块定位与整体架构mcp_servers/outlook是 Klavis 开源仓库Klavis AI一个让 AI Agent 可靠使用工具做事的 MCP 集成平台中的邮件域 MCP 服务器。它以 Python 实现基于mcp官方 SDK 构建通过 Microsoft Graph API 与 Outlook 邮箱交互向外暴露一套outlookMail_*前缀的工具。从源码结构看模块分为三层层次文件职责入口/协议层server.pyMCP 服务注册、工具 Schema 声明、双传输协议SSE StreamableHTTP、响应归一化工具实现层tools/mailFolder.py、tools/messages.py封装对 Microsoft Graph API 的具体 HTTP 调用认证/客户端层tools/base.py访问令牌获取与 Graph 客户端构建其中server.py中Server(outlookMail-mcp-server)创建 MCP 实例并在list_tools()中注册全部工具、在call_tool()中完成参数透传与返回结果归一化见 server.py。权限范围Scopes文档明确规定了模块使用的 5 个 Microsoft Graph 委派权限这是应用注册时需要在 Azure 门户中为应用配置的最小权限集Scope用途Mail.Read读取用户邮件Mail.ReadWrite读写用户邮件MailboxSettings.Read读取邮箱设置MailboxSettings.ReadWrite读写邮箱设置Mail.Send以登录用户身份发送邮件注意README 与源码均强调绝大多数操作需要Mail.ReadWrite而管理类操作Admin operations需要委派权限delegated permissions。发送草稿需要Mail.Send。工具清单全解析README 将 16 个工具划分为文件夹管理与消息操作两大类。下面结合 server.py 中声明的实际inputSchema补齐每个工具的必填/可选参数与默认值。 文件夹管理5 个工具工具名说明参数含源码中的默认值outlookMail_create_mail_folder新建邮件文件夹必填display_name可选is_hiddenboolean默认FalseoutlookMail_list_folders列出全部邮件文件夹可选include_hiddenboolean默认True对应 Graph 的includeHiddenFolderstrueoutlookMail_get_mail_folder_details按 ID 查询文件夹详情必填folder_idoutlookMail_update_folder_display_name重命名文件夹必填folder_id、display_nameoutlookMail_delete_folder删除文件夹必填folder_id✉️ 消息操作11 个工具工具名说明参数含源码中的默认值outlookMail_read_message按 ID 读取邮件正文必填message_idoutlookMail_list_messages列出收件箱邮件可选topint默认10范围 1–1000、filter_queryOData$filter、orderbyOData$orderby、select逗号分隔字段列表outlookMail_list_messages_from_folder列出指定文件夹内邮件必填folder_id可选top默认10、filter_query、orderby、selectoutlookMail_create_draft创建新草稿POST必填subject、body_contentHTML、to_recipients可选cc_recipients、bcc_recipientsoutlookMail_update_draft更新已有草稿PATCH必填message_id可选subject、body_content、to_recipients、cc_recipients、bcc_recipientsoutlookMail_create_reply_draft创建回复草稿必填message_id、commentoutlookMail_create_reply_all_draft创建全部回复草稿必填message_id可选comment默认outlookMail_create_forward_draft创建转发草稿必填message_id、comment、to_recipientsoutlookMail_send_draft发送草稿必填message_idoutlookMail_delete_draft删除草稿必填message_idoutlookMail_move_message移动邮件到其他文件夹必填message_id、destination_folder_id支持 well-known 名如deleteditems或自定义文件夹 IDREADME 中的outlookMail_get_mail_folder在源码注册名中实际为outlookMail_get_mail_folder_details见 server.py本文以源码为准。核心功能深度解析草稿全生命周期控制这是模块最完整的子能力create → update → reply → replyAll → forward → send → delete七个动作覆盖草稿的完整生命周期。以创建草稿为例tools/messages.py 中outlookMail_create_draft的调用链是请求POST https://graph.microsoft.com/v1.0/me/messagespayload 结构为{subject: ..., body: {contentType: HTML, content: ...}}收件人列表由字符串数组自动构造成 Graph 规范结构[{emailAddress: {address: email}}]转发草稿createForward、回复草稿createReply/createReplyAll分别对应 Graph 的 action 端点/me/messages/{id}/createForward、/createReply、/createReplyAll均以POST提交{comment: ...}与可选收件人。OData 查询参数让 Agent 精准取件outlookMail_list_messages与outlookMail_list_messages_from_folder将 OData 查询透传到 Graph API$top/$filter/$orderby/$select源码中给出了可直接使用的过滤表达式示例见 tools/messages.pyisRead eq false # 只看未读 importance eq high # 高优先级 from/emailAddress/address eq exampleexample.com subject eq Welcome receivedDateTime ge 2025-07-01T00:00:00Z # 某日期之后收到 hasAttachments eq true # 带附件 isRead eq false and importance eq high # 组合过滤排序示例receivedDateTime desc最新在前、subject asc。字段裁剪示例subject,from,receivedDateTime。附件与文件夹元数据处理虽然 README 将附件处理列为 Key Feature列出附件、获取附件详情、大文件支持当前tools/下主要通过ATTACHMENT_RULES映射见 server.py在返回邮件时将attachments数组归一化为attachmentId / name / size / type / inline / lastModified六个字段。outlookMail_list_folders的归一化响应结构为{count: N, folders: [...]}见 server.py。响应归一化面向 Agent 的字段映射模块在server.py中通过normalize(source, mapping)把 Graph API 的原始 JSON 转换为更简洁、对 LLM 更友好的字段命名。其核心机制server.py是按映射规则点号取值或执行 lambda值为None的字段直接从输出中剔除。三组核心映射规则FOLDER_RULESitemId ← id、name ← displayName、messageCount ← totalItemCount、unreadCount ← unreadItemCount、parentId ← parentFolderId、childCount ← childFolderCount、size ← sizeInBytes、hidden ← isHidden、wellKnownName见 server.pyMESSAGE_RULEStitle ← subject、preview ← bodyPreview、content ← body.content、importance、isRead、hasAttachments、senderEmail/senderName、fromEmail/fromName、toRecipients/ccRecipients/bccRecipients/replyTolambda 递归归一化、webLink、received/sent/created等见 server.pyATTACHMENT_RULESattachmentId ← id、name、size、type ← contentType、inline ← isInline、lastModified见 server.py这意味着 Agent 拿到的每条消息都是精简字段token 开销更小、字段含义更直观。认证机制令牌的三级获取链认证是部署该模块最关键的一环tools/base.py 的get_auth_token()按优先级依次尝试请求上下文令牌auth_token_contextContextVar由server.py在每次请求进入时从x-auth-data请求头Base64 编码的 JSON含access_token解码后注入见 server.py环境变量AUTH_DATAJSON 字符串形式的{access_token: ...}兜底环境变量OUTLOOK_ACCESS_TOKEN传统直配令牌方式legacy fallback。随后get_outlookMail_client()tools/base.py构建{ base_url: https://graph.microsoft.com/v1.0, headers: {Authorization: Bearer token} }由于server.py启动时执行load_dotenv()见 server.py也可在项目根目录放置.env文件提供AUTH_DATA或OUTLOOK_ACCESS_TOKEN。OUTLOOK_MCP_SERVER_PORT环境变量控制监听端口默认5000。双传输协议与部署方式server.py同时暴露两种 MCP 传输协议server.py传输端点说明SSEGET /ssePOST /messages/传统 SSE 流式传输StreamableHTTPPOST /mcp新版流式 HTTP 传输支持--json-response切换为 JSON 响应启动命令main()的 click 参数见 server.pypython -u server.py \ --port 5000 \ --log-level INFO \ --json-response三个 CLI 参数分别为--portHTTP 监听端口默认读取OUTLOOK_MCP_SERVER_PORT否则 5000、--log-levelDEBUG/INFO/WARNING/ERROR/CRITICAL、--json-response布尔开关启用 StreamableHTTP 的 JSON 响应。Docker 部署仓库提供了开箱即用的 Dockerfile基于python:3.12-slim安装gcc系统依赖后按requirements.txt安装 Python 包mcp1.12.3、httpx、click、starlette、python-dotenv暴露5000端口以python -u server.py启动-u保证日志实时输出。典型构建运行方式docker build -f mcp_servers/outlook/Dockerfile -t klavis-outlook-mcp . docker run -p 5000:5000 -e AUTH_DATA{access_token:YOUR_TOKEN} klavis-outlook-mcp运行环境要求README 明确的使用前提具备 Microsoft Graph API 访问能力、拥有正确的认证权限、Python 3.8 环境pyproject.toml声明requires-python 3.13Docker 镜像使用 3.12实际以容器或本地解释器版本为准。在 Klavis 平台中接入该 MCP 服务器作为 Klavis 平台众多 MCP 服务器之一该模块遵循统一的工具 认证头接入模式AI Agent 调用outlookMail_*工具时Klavis 网关在请求中注入x-auth-data头携带 OAuth 令牌模块端extract_access_token解码后即完成授权。因此在实际使用中你不需要在服务器环境里硬编码令牌只需在 Klavis 侧完成 Outlook 应用的 OAuth 授权即可实现按用户隔离的邮箱访问详见仓库根目录的 MCP_SERVER_GUIDE.md 与_oauth_support/目录的 OAuth 支持方案。典型使用场景与调用示例场景一Agent 汇总未读高优先级邮件调用outlookMail_list_messages参数filter_query isRead eq false and importance eq high、orderby receivedDateTime desc、top 20即可获得归一化后的{count: N, messages: [...]}列表字段含title、preview、senderEmail、received等可直接用于摘要生成。场景二起草并发送一封邮件outlookMail_create_draftsubject、body_contentHTML、to_recipients必填outlookMail_update_draft追加cc_recipients或修正正文仅草稿态可改outlookMail_send_draft传入上一步返回的id成功返回{success: Draft sent successfully}Graph 返回 200/202/204 任一状态即视为成功见 tools/messages.py。场景三邮件归档整理用outlookMail_move_message将邮件移入deleteditems或其他文件夹 ID用outlookMail_list_folders先获取文件夹与messageCount、unreadCount帮助 Agent 判断整理策略。小结mcp_servers/outlook是一个功能完整、面向 AI Agent 设计的 Outlook 邮件 MCP 服务器16 个工具覆盖文件夹与邮件两大域草稿生命周期、OData 查询、字段归一化、三级认证链、双传输协议一应俱全。将它与 README 中列出的 Scope 结合配置即可让 AI Agent 安全、精准地完成读信、写信、转发、归档等邮件自动化任务。进一步的参数规格与响应格式可随时查阅源码中各工具的完整 docstring 与inputSchema声明。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考