金大哥 - outlook-mcp MCP 详情

article

README

🚀 Outlook MCP Server

Outlook MCP Server 是一个模型上下文协议（MCP）服务器，它借助 Microsoft Graph API 让 Claude 能够访问 Microsoft Outlook。该服务器支持多账户操作，可进行远程部署，能全面管理邮件、日历和文件夹。

🚀 快速开始

1. 安装依赖

npm install

2. 配置 Azure 应用注册

在 Azure 门户创建一个 Azure 应用注册。
设置重定向 URI：
- http://localhost:3333/auth/callback
- 远程使用时：https://your-domain.com/auth/callback
授予权限：Mail.ReadWrite、Calendars.ReadWrite、offline_access

3. 环境设置

将 .env.example 复制为 .env 并进行配置：

# Azure 应用注册
MS_CLIENT_ID=your-azure-client-id
MS_CLIENT_SECRET=your-azure-client-secret
OUTLOOK_CLIENT_ID=your-azure-client-id
OUTLOOK_CLIENT_SECRET=your-azure-client-secret

# 服务器配置
USE_TEST_MODE=false
MCP_PORT=3001

4. Claude 桌面端配置

在你的 Claude 桌面端配置中添加以下内容：

{
  "mcpServers": {
    "outlook-mcp": {
      "command": "node",
      "args": ["/path/to/outlook-mcp/index.js"],
      "env": {
        "USE_TEST_MODE": "false"
      }
    }
  }
}

💻 使用示例

本地模式（默认）

npm start

通过标准输入输出与 Claude 桌面端集成运行。

远程模式

npm run start-remote

在端口 3001 上运行 HTTP 服务器，MCP 端点为 /mcp。

测试模式

npm run test-mode

使用模拟数据进行开发。

✨ 主要特性

多账户支持

可同时管理多个 Outlook 账户。
每个账户单独进行身份验证和令牌存储。
支持账户特定操作和数据隔离。

邮件管理

列出、搜索和阅读邮件。
发送邮件和创建草稿。
回复邮件。
管理文件夹并移动邮件。
处理附件。

日历管理

列出日历事件。
创建、更新和删除事件。
接受/拒绝会议邀请。
管理日历权限。

文件夹和规则管理

创建和管理邮件文件夹。
设置邮件规则和过滤器。
组织邮箱结构。

🛠️ MCP 工具

身份验证

authenticate - 添加新的 Outlook 账户。
check-auth-status - 查看账户身份验证状态。
list-accounts - 列出所有已配置的账户。
remove-account - 删除账户。

邮件工具

list-emails - 列出带有过滤选项的邮件。
read-email - 读取特定邮件内容。
send-email - 发送新邮件。
create-draft - 创建邮件草稿。
reply-to-email - 回复现有邮件。
search-emails - 按条件搜索邮件。
mark-as-read - 将邮件标记为已读/未读。

日历工具

list-calendar-events - 列出日历事件。
create-calendar-event - 创建新事件。
delete-calendar-event - 删除事件。
accept-calendar-event - 接受会议邀请。
decline-calendar-event - 拒绝会议邀请。

文件夹工具

list-folders - 列出邮件文件夹。
create-folder - 创建新文件夹。
move-email - 将邮件移动到文件夹。

🚀 部署

Railway 部署

将你的 GitHub 仓库连接到 Railway。
在 Railway 控制台设置环境变量。
在代码推送时自动部署。

Railway 的环境变量设置：

MS_CLIENT_ID=your-azure-client-id
MS_CLIENT_SECRET=your-azure-client-secret
OUTLOOK_CLIENT_ID=your-azure-client-id
OUTLOOK_CLIENT_SECRET=your-azure-client-secret
NODE_ENV=production
USE_TEST_MODE=false

Docker 部署

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --production
COPY . .
EXPOSE 3001
CMD ["npm", "run", "start-remote"]

手动服务器设置

克隆仓库。
安装依赖：npm ci --production。
配置环境变量。
启动服务器：npm run start-remote。
如有需要，配置反向代理（nginx/Apache）。

📚 详细文档

架构

outlook-mcp/
├── auth/                  # 身份验证和账户管理
│   ├── index.js          # 主要身份验证模块导出
│   ├── server.js         # OAuth 服务器（从根目录移来）
│   ├── account-manager.js # 多账户管理
│   ├── token-manager.js  # 令牌存储和刷新
│   └── tools.js          # 身份验证 MCP 工具
├── calendar/             # 日历操作
├── email/               # 邮件操作
├── folder/              # 文件夹管理
├── rules/               # 邮件规则
├── utils/               # 共享工具
│   ├── graph-api.js     # Graph API 助手
│   ├── odata-helpers.js # OData 查询构建器
│   ├── permissions.js   # 权限检查
│   └── mock-data.js     # 测试数据
├── Scripts/             # 部署和管理脚本
├── config.js            # 配置管理
├── index.js             # 主要服务器入口点
└── package.json         # 依赖和脚本

安全

最佳实践

使用环境变量存储所有机密信息。
每个账户单独存储令牌。
自动刷新令牌。
在生产环境中强制使用 HTTPS。
为远程访问配置 CORS。

令牌管理

令牌存储在 ~/.outlook-mcp-accounts/ 中。
在过期前自动刷新。
使用唯一账户 ID 安全存储令牌。
账户删除时清理令牌。

故障排除

常见问题

“No accounts configured”

解决方案：使用 authenticate 工具添加账户。

“Authentication required for account X”

解决方案：重新对特定账户进行身份验证。

浏览器中出现 CORS 错误

解决方案：检查你的域名的 CORS 配置。

端口已被使用

解决方案：更改 MCP_PORT 环境变量。

健康检查

本地：使用 check-auth-status 工具。
远程：访问 http://localhost:3001/health。

日志

服务器日志输出到标准错误输出。
身份验证事件记录账户 ID。
包含错误详细信息以便调试。

开发

前提条件

Node.js 14+。
Azure 应用注册。
Microsoft Graph API 权限。

脚本

npm start - 本地标准输入输出模式。
npm run start-remote - 远程 HTTP 模式。
npm run auth-server - 仅启动 OAuth 服务器。
npm run test-mode - 使用模拟数据运行。
npm run inspect - 使用 MCP 检查器运行。

贡献

分叉仓库。
创建功能分支。
编写测试并进行更改。
更新文档。
提交拉取请求。

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。

📞 支持

GitHub 问题：报告错误
文档：本 README
MCP 协议：modelcontextprotocol.io
Microsoft Graph：docs.microsoft.com/graph