使用说明

模块化Outlook MCP服务器

模块化MCP（模型上下文协议）服务器，通过Microsoft Graph API将Claude与Microsoft Outlook连接起来，使用 仅应用程序（客户端凭据）身份验证 --无需浏览器登录。

MCPHub认证https://mcphub.com/mcp-servers/ryaker/outlook-mcp

目录结构

├── index.ts                 # Main entry point
├── config.ts                # Configuration settings
├── types.ts                 # Shared TypeScript type definitions
├── auth/                    # Authentication modules
│   ├── index.ts             # Authentication exports
│   ├── token-manager.ts     # Token management (client credentials)
│   └── tools.ts             # Auth-related tools
├── calendar/                # Calendar functionality
│   ├── index.ts             # Calendar exports and tool schemas
│   ├── types.ts             # Calendar type definitions
│   ├── list.ts              # List events (calendarView)
│   ├── create.ts            # Create event
│   ├── delete.ts            # Delete event
│   ├── cancel.ts            # Cancel event
│   ├── accept.ts            # Accept event
│   └── decline.ts           # Decline event
├── config/                  # Configuration modules
│   └── mailbox-permissions.ts  # Mailbox permission restrictions
├── email/                   # Email functionality
│   ├── index.ts             # Email exports and tool schemas
│   ├── folder-utils.ts      # Folder resolution utilities
│   ├── list.ts              # List emails
│   ├── search.ts            # Search emails
│   ├── read.ts              # Read email
│   ├── send.ts              # Send email
│   ├── mark-as-read.ts      # Mark as read/unread
│   ├── categories.ts        # Email categories management
│   └── archive-delete.ts    # Archive and delete emails
├── folder/                  # Folder management
│   ├── index.ts             # Folder exports and tool schemas
│   ├── list.ts              # List folders
│   ├── create.ts            # Create folder
│   └── move.ts              # Move emails between folders
├── rules/                   # Inbox rules
│   ├── index.ts             # Rules exports and tool schemas
│   ├── list.ts              # List rules
│   └── create.ts            # Create rule
├── tests/                   # Test suite
│   ├── mailbox-permissions.test.ts
│   ├── tool-schemas.test.ts
│   ├── error-responses.test.ts
│   └── mock-mode.test.ts
└── utils/                   # Utility functions
    ├── graph-api.ts         # Microsoft Graph API helper
    └── mock-data.ts         # Test mode data

特性

仅应用程序身份验证：使用客户端凭据流--无需浏览器登录或用户交互
电子邮件管理：列出、搜索、阅读、发送、标记为已读
类别管理：获取主类别并在电子邮件上设置类别
存档和删除：将电子邮件存档到存档文件夹，软/硬删除
日程管理：列出即将发生的事件（重复通知），创建、接受、拒绝、取消、删除
文件夹管理：在文件夹之间列出、创建和移动电子邮件
收件箱规则：列出、创建、重新排序规则
邮箱权限限制：可配置每个邮箱的访问控制
多邮箱：通过访问多个邮箱 mailbox 每个工具上的参数
测试模式：在没有实际API调用的情况下进行测试的模拟响应
TypeScript：具有严格模式的全类型代码库

快速开始

安装依赖项: bun install
Azure设置：使用应用程序权限在Azure门户中注册应用程序（见下文）
配置环境：复制 .env.example 到 .env 并添加您的Azure凭据
配置Claude：使用服务器路径更新您的Claude Desktop配置
开始使用：不需要身份验证服务器--凭据会自动从env加载

安装

先决条件

Bun运行时 --快速JavaScript/TypeScript运行时
用于应用注册的Azure帐户

bun install

Bun原生支持TypeScript和自动加载 .env 文件，因此不需要额外的工具。

Azure应用程序注册和配置

此服务器使用 仅限应用程序（客户端凭据） 身份验证。该应用程序代表您的组织行事，而不是代表特定的登录用户。这需要管理员同意应用程序权限。

1.应用注册

打开 Azure 门户
首选 应用程序注册 → 新注册
输入名称（例如，“Outlook MCP服务器”）
选择 仅此组织目录中的帐户 （单租户）
不需要重定向URI --客户端凭据流没有浏览器重定向
点击注册
复制 应用程序（客户端）ID → 这是你的 MS_CLIENT_ID
复制 目录（租户）ID 从“概述”页面→ 这是你的 MS_TENANT_ID

2.应用程序权限

⚠️ 这些是应用权限（未委派）。它们需要管理员同意。

首选 API权限 → 添加权限 → 微软图形 → 应用程序权限
添加以下权限：

许可	目的
`Mail.Read`	阅读电子邮件
`Mail.ReadWrite`	移动、存档、更新电子邮件
`Mail.Send`	发送电子邮件
`Calendars.ReadWrite`	读取和修改日历事件
`MailboxSettings.ReadWrite`	读取和管理收件箱规则

点击 添加权限
点击 授予[您的组织]管理员同意 --这是应用程序权限所必需的

3.客户机密

首选 证书和秘密 → 客户机密 → 新客户机密
输入描述并选择可用的最长过期时间
点击添加
⚠️ 复制秘密价值（不是秘密ID）立即显示，不会再显示

配置

环境变量

创建一个 .env 项目根目录中的文件：

cp .env.example .env

编辑 .env:

MS_TENANT_ID=your-directory-tenant-id-here
MS_CLIENT_ID=your-application-client-id-here
MS_CLIENT_SECRET=your-client-secret-VALUE-here
USE_TEST_MODE=false

重要：使用秘密价值，而不是秘密ID。

Claude桌面配置

复制自 claude-config-sample.json 并更新路径和凭据：

{
  "mcpServers": {
    "outlook-assistant": {
      "command": "bun",
      "args": [
        "/absolute/path/to/outlook-mcp/index.ts"
      ],
      "env": {
        "USE_TEST_MODE": "false",
        "OUTLOOK_TENANT_ID": "your-tenant-id-here",
        "OUTLOOK_CLIENT_ID": "your-client-id-here",
        "OUTLOOK_CLIENT_SECRET": "your-client-secret-here"
      }
    }
  }
}

身份验证流程

不需要浏览器登录或身份验证服务器。需要时，服务器会使用您的应用程序凭据自动获取访问令牌：

Claude启动MCP服务器
服务器读取 MS_TENANT_ID, MS_CLIENT_ID, MS_CLIENT_SECRET 从环境
在第一个API调用中，通过 POST /oauth2/v2.0/token （客户端凭据）
令牌缓存在内存中，到期时自动刷新

您可以使用验证凭据是否正常工作 authenticate 克劳德的工具。

邮箱参数

所有访问Outlook数据的工具都需要 mailbox 指定要操作哪个邮箱的参数（例如。， chi@desertservices.net).这就是服务器如何知道在仅应用程序模式下访问哪个用户的数据。

示例：“列出我最近10封来自的电子邮件chi@desertservices.net"

邮箱权限

写入操作（发送、存档、删除、创建/修改规则、移动电子邮件、创建事件）仅限于特定邮箱，以防止意外修改。

允许的邮箱（完全访问）

配置于 config/mailbox-permissions.ts:

contracts@desertservices.net
chi@desertservices.net
dustpermits@desertservices.net

所有其他邮箱均为只读。尝试从未列出的邮箱进行写入操作会返回错误。

发展

bun run start        # Start the MCP server
bun test             # Run tests (114 pass)
bun run typecheck    # TypeScript type checking
bun run lint         # Check formatting (Biome/Ultracite)
bun run lint:fix     # Auto-fix formatting
bun run inspect      # Open MCP Inspector for interactive testing

测试模式

USE_TEST_MODE=true bun run start           # Start with mock data
USE_TEST_MODE=true bun test tests/mock-mode.test.ts  # Run integration tests

故障排除

身份验证错误

启动时“缺少凭据”

设置所有三个环境变量： MS_TENANT_ID, MS_CLIENT_ID, MS_CLIENT_SECRET

“无效的客户端机密”（AADST7000215）

您使用了Secret ID而不是Secret值。转到Azure门户→ 证书和秘密，并复制价值列。

403禁止API调用

尚未授予应用程序权限的管理员同意。转到Azure门户→ API权限→ 授予管理员同意.

403规则操作

确保 MailboxSettings.ReadWrite 授予应用程序权限（不仅仅是 Mail.ReadWrite).

“不允许从此邮箱发送”

邮箱不在 canSend 列入 config/mailbox-permissions.ts。添加它或使用允许的邮箱。

API错误

“cpim_sts_不支持的_endpoint”

您的服务器版本已过时——此错误意味着 me/ 使用了终点。更新到最新版本。

400在搜索与附件过滤器

这是旧版本中的一个已知错误-- $search 和 $filter 不能合并。已在v2.1.0中修复。

扩展服务器

创建新的模块目录（例如。， contacts/)
分别实现工具处理程序 .ts 具有正确TypeScript类型的文件
从模块导出工具定义 index.ts 文件
将工具导入并添加到 TOOLS 数组in index.ts
将任何共享类型添加到 types.ts 从项目根源
包括a mailbox 进行API调用的所有工具架构中的必需参数