企业官网建设流程全解析

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.py中Server("outlookMail-mcp-server")创建 MCP 实例，并在list_tools()中注册全部工具、在call_tool()中完成参数透传与返回结果归一化（见 server.py）。

权限范围（Scopes）

文档明确规定了模块使用的 5 个 Microsoft Graph 委派权限，这是应用注册时需要在 Azure 门户中为应用配置的最小权限集：

注意：README 与源码均强调，绝大多数操作需要Mail.ReadWrite；而管理类操作（Admin operations）需要委派权限（delegated permissions）。发送草稿需要Mail.Send。

工具清单全解析

README 将 16 个工具划分为"文件夹管理"与"消息操作"两大类。下面结合 server.py 中声明的实际inputSchema补齐每个工具的必填/可选参数与默认值。

📁 文件夹管理（5 个工具）

✉️ 消息操作（11 个工具）

README 中的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/messages
• payload 结构为{"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.py）：

isRead eq false # 只看未读 importance eq 'high' # 高优先级 from/emailAddress/address eq 'example@example.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_RULES：itemId ← id、name ← displayName、messageCount ← totalItemCount、unreadCount ← unreadItemCount、parentId ← parentFolderId、childCount ← childFolderCount、size ← sizeInBytes、hidden ← isHidden、wellKnownName（见 server.py）
• MESSAGE_RULES：title ← subject、preview ← bodyPreview、content ← body.content、importance、isRead、hasAttachments、senderEmail/senderName、fromEmail/fromName、toRecipients/ccRecipients/bccRecipients/replyTo（lambda 递归归一化）、webLink、received/sent/created等（见 server.py）
• ATTACHMENT_RULES：attachmentId ← id、name、size、type ← contentType、inline ← isInline、lastModified（见 server.py）

这意味着 Agent 拿到的每条消息都是精简字段，token 开销更小、字段含义更直观。

认证机制：令牌的三级获取链

认证是部署该模块最关键的一环，tools/base.py 的get_auth_token()按优先级依次尝试：

1. 请求上下文令牌：auth_token_context（ContextVar）由server.py在每次请求进入时，从x-auth-data请求头（Base64 编码的 JSON，含access_token）解码后注入（见 server.py）；
2. 环境变量AUTH_DATA：JSON 字符串形式的{"access_token": "..."}兜底；
3. 环境变量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）：

启动命令（main()的 click 参数，见 server.py）：

python -u server.py \ --port 5000 \ --log-level INFO \ --json-response

三个 CLI 参数分别为：--port（HTTP 监听端口，默认读取OUTLOOK_MCP_SERVER_PORT，否则 5000）、--log-level（DEBUG/INFO/WARNING/ERROR/CRITICAL）、--json-response（布尔开关，启用 StreamableHTTP 的 JSON 响应）。

Docker 部署

仓库提供了开箱即用的 Dockerfile，基于python:3.12-slim，安装gcc系统依赖后按requirements.txt安装 Python 包（mcp==1.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.13"，Docker 镜像使用 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等，可直接用于摘要生成。

场景二：起草并发送一封邮件

1. outlookMail_create_draft：subject、body_content（HTML）、to_recipients必填；
2. outlookMail_update_draft：追加cc_recipients或修正正文（仅草稿态可改）；
3. 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