使用说明

EWS MCP服务器

一个完整的模型上下文协议（MCP）服务器，与Microsoft Exchange Web服务（EWS）连接，使AI助手能够与Exchange交互以进行电子邮件、日历、联系人和任务操作。

📦 Docker镜像：预构建图像将在 ghcr.io/azizmazrou/ews-mcp:latest 一旦合并到主分支。目前，在本地构建 docker build -t ews-mcp-server . -请参阅 GHCR_STATUS.md 了解详情。

特性

✅ 电子邮件操作：发送、阅读、搜索、删除、移动、，复制电子邮件与 固定的 附件支持
- 分发列表支持：按姓名向通讯组发送电子邮件
✅ 附件内容提取：从PDF、DOCX、XLSX、TXT文件读取文本（阿拉伯语/UTF-8支持）
✅ 日历管理：创建、更新、删除约会、回复会议， 人工智能会议时间查找器
✅ 联系人管理：Exchange联系人的完整CRUD操作
✅ 联系情报：跨GAL和电子邮件历史、通信分析、网络分析的高级联系人搜索
✅ 任务管理：创建和管理Exchange任务
✅ 文件夹管理：创建、删除、重命名、移动邮箱文件夹
✅ 高级搜索：对话线程，跨电子邮件内容的全文搜索
✅ 不在办公室：配置带有日程安排的自动回复
✅ 多重身份验证：支持OAuth2、基本授权和NTLM
✅ 时区支持：正确处理时区（通过亚洲/利雅得、UTC等测试）
✅ HTTP/SSE传输：支持web客户端的stdio和HTTP/SSE（兼容n8n）
✅ Docker就绪：采用最佳实践的生产就绪集装箱化
✅ 速率限制：内置速率限制，自动重试（指数回退）
✅ 错误处理：使用@handle_ews_errors装饰器进行全面的错误处理
✅ 审计日志：跟踪所有操作的合规性（仅记录到stderr）

v2.1的新增功能🎯

2.1版本新增 联系情报 能力和 多账户支持:

多账户支持🔐

承载令牌身份验证：使用HTTP授权标头在多个Exchange帐户之间动态切换
帐户配置：在中配置多个帐户 accounts.json 具有唯一的API密钥
连接缓存：为频繁访问的帐户提供高效的连接重用
向后兼容：如果没有提供Bearer令牌，则回退到环境变量

看 BEARER_AUTH_GUIDE.md 有关详细的设置说明。

联系人智能工具（3个新工具）

统一联系人搜索

查找人员 -在全球地址列表（GAL）、电子邮件历史记录和域中搜索
- 按通信频率和近距进行智能排名
- 多源重复数据删除（GAL+电子邮件历史记录）
- 阿拉伯语支持（UTF-8）
- 全域搜索（例如，来自@example.com的所有联系人）

通信分析

get_通信_历史 -与任何联系人的详细关系分析
- 电子邮件数量统计（发送/接收/总计）
- 沟通时间表（每月汇总）
- 从电子邮件主题中提取主题
- 带有日期的最近电子邮件预览

网络智能

分析网络 -专业网络分析
- 按电子邮件数量排列的顶级联系人
- 基于域的组织分组
- 休眠关系检测（与您失去联系的联系人）
- VIP身份（高流量+近期活动）
- 综合概述和汇总统计数据

功能亮点

在多个来源中查找任何人

# Search by name across all sources
find_person(
    query="John Doe",
    search_scope="all",  # Search GAL + email history
    include_stats=True
)

# Find all contacts from a specific domain
find_person(
    query="@example.com",
    search_scope="domain"
)

分析沟通模式

# Get detailed history with any contact
get_communication_history(
    email="colleague@example.com",
    days_back=365,
    include_topics=True
)
# Returns: stats, timeline, top topics, recent emails

了解您的专业网络

# Identify VIP contacts (high volume + recent)
analyze_network(
    analysis_type="vip",
    days_back=90,
    vip_email_threshold=10
)

# Find dormant relationships to reconnect
analyze_network(
    analysis_type="dormant",
    dormant_threshold_days=60
)

# Analyze by organization/domain
analyze_network(
    analysis_type="by_domain",
    top_n=20
)

v2.0中的新增功能🚀

2.0版本扩展了EWS MCP服务器 28个MVP工具到40个企业级工具，添加了强大的新功能：

新工具（新增12个）

文件夹管理（4个工具）

创建文件夹 -使用自定义文件夹类创建新的邮箱文件夹
删除文件夹 -删除文件夹（软文件夹或永久文件夹）
重命名文件夹 -重命名现有文件夹
move_folder -将文件夹移动到新的父位置

增强型附件（2个工具）

添加附件 -通过文件路径或具有内联支持的base64内容添加附件
删除附件 -按ID或名称删除附件

高级搜索（2个工具）

搜索_对话 -查找对话线程中的所有电子邮件
full_text_search -带有区分大小写和精确短语选项的全文搜索

外出（2个工具）

设置的集合 -配置自动回复（启用/计划/禁用）
get_of_setting -检索当前处于活动状态的OOF设置

日历增强（1个工具）

find_meeting_times -基于人工智能的会议时间查找器，通过智能评分分析与会者的可用性

电子邮件增强（1个工具）

复制邮件 -将电子邮件复制到文件夹，同时保留原件

功能亮点

智能会议日程安排

# Find optimal meeting times across multiple attendees
find_meeting_times(
    attendees=["alice@company.com", "bob@company.com", "carol@company.com"],
    duration_minutes=60,
    preferences={
        "prefer_morning": True,
        "working_hours_start": 9,
        "working_hours_end": 17,
        "avoid_lunch": True
    }
)
# Returns scored suggestions with availability analysis

对话线程

# Track entire email conversations
search_by_conversation(
    message_id="email-123"  # or conversation_id directly
)
# Returns all emails in the thread

高级文件夹组织

# Organize your mailbox programmatically
create_folder(folder_name="Projects/2025/Q1", parent_folder="inbox")
move_folder(folder_id="folder-123", destination_parent_folder="archive")
rename_folder(folder_id="folder-123", new_name="Completed Projects")

办公室外自动化

# Schedule OOF for vacation
set_oof_settings(
    state="Scheduled",
    internal_reply="I'm on vacation",
    external_reply="I'm currently out of office",
    start_time="2025-12-20T00:00:00",
    end_time="2025-12-31T23:59:59",
    external_audience="Known"
)

快速开始

使用预构建的Docker镜像（最简单）

选择您的身份验证方法：

选项1：基本身份验证（最快设置-1分钟）

最适合：测试、本地交换、快速演示

# Pull the latest image
docker pull ghcr.io/azizmazrou/ews-mcp:latest

# 3. Create .env file with Basic Auth
cat > .env <<EOF
EWS_SERVER_URL=https://mail.company.com/EWS/Exchange.asmx
EWS_EMAIL=user@company.com
EWS_AUTODISCOVER=false
EWS_AUTH_TYPE=basic
EWS_USERNAME=user@company.com
EWS_PASSWORD=your-password
TIMEZONE=UTC
LOG_LEVEL=INFO
EOF

# 4. Run the container
docker run -d \
  --name ews-mcp-server \
  --env-file .env \
  -v $(pwd)/logs:/app/logs \
  ghcr.io/azizmazrou/ews-mcp:latest

# View logs - look for "✓ Successfully connected to Exchange"
docker logs -f ews-mcp-server

或者使用预先配置的模板:

cp .env.basic.example .env
# Edit .env with your credentials
docker run -d --name ews-mcp --env-file .env ghcr.io/azizmazrou/ews-mcp:latest

选项2:OAuth2身份验证（生产环境-Office 365）

最适合：Office 365、生产环境、增强的安全性

# Pull the latest image
docker pull ghcr.io/azizmazrou/ews-mcp:latest

# Use pre-configured OAuth2 template
cp .env.oauth2.example .env

# Edit .env with your Azure AD credentials:
# - EWS_CLIENT_ID (from Azure AD app registration)
# - EWS_CLIENT_SECRET (from Azure AD app registration)
# - EWS_TENANT_ID (from Azure AD app registration)
# See OAuth2 Setup section below for detailed instructions

# Run the container
docker run -d \
  --name ews-mcp-server \
  --env-file .env \
  -v $(pwd)/logs:/app/logs \
  ghcr.io/azizmazrou/ews-mcp:latest

# View logs
docker logs -f ews-mcp-server

从源头构建

# Clone repository
git clone https://github.com/azizmazrou/ews-mcp.git
cd ews-mcp

# Copy and configure environment
cp .env.example .env
# Edit .env with your Exchange credentials

# Build and run with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f

本地开发

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements-dev.txt

# Configure environment
cp .env.example .env
# Edit .env with your credentials

# Run server
python -m src.main

配置

根据Exchange设置选择身份验证方法：

身份验证方法	用例	设置时间	安全性
基本认证	测试、本地交换	⚡ 1分钟	⚠️ 中等
OAuth2	Office 365，生产版🕐 10分钟	✅ 高
身份验证	Windows域，本地部署	🕐 5分钟	⚠️ 中等

基本身份验证（最简单-用于测试/本地）

最适合：快速测试、本地Exchange服务器、旧版设置

⚠️ 备注：Microsoft正在为Office 365弃用基本身份验证。将OAuth2用于生产Office 365环境。

快速设置（30秒）

创建 .env 文件:

cat > .env <<EOF
# Exchange Server
EWS_SERVER_URL=https://mail.company.com/EWS/Exchange.asmx
EWS_EMAIL=user@company.com
EWS_AUTODISCOVER=false

# Basic Authentication
EWS_AUTH_TYPE=basic
EWS_USERNAME=user@company.com
EWS_PASSWORD=your-password

# Server Configuration
LOG_LEVEL=INFO
EOF

运行服务器:

docker run -d --name ews-mcp --env-file .env ghcr.io/azizmazrou/ews-mcp:latest

验证它是否正常工作:

docker logs ews-mcp
# Look for "✓ Successfully connected to Exchange"

就是这样！服务器现在正在使用基本身份验证运行。

使用预配置模板

# Copy Basic Auth template
cp .env.basic.example .env

# Edit with your credentials
nano .env  # or your preferred editor

# Run
docker run -d --env-file .env ghcr.io/azizmazrou/ews-mcp:latest

交互式设置脚本

为了更简单的设置，请使用交互式脚本：

# Run the setup script
./scripts/setup-basic-auth.sh

# Follow the prompts to:
# - Enter your Exchange server
# - Provide email and password
# - Automatically create .env
# - Pull Docker image
# - Start the server

用于内部交换

# Find your EWS endpoint
# Usually: https://mail.yourcompany.com/EWS/Exchange.asmx
# Or: https://exchange.yourcompany.com/EWS/Exchange.asmx

cat > .env <<EOF
EWS_SERVER_URL=https://mail.yourcompany.com/EWS/Exchange.asmx
EWS_EMAIL=user@yourcompany.com
EWS_AUTODISCOVER=false
EWS_AUTH_TYPE=basic
EWS_USERNAME=user@yourcompany.com
EWS_PASSWORD=your-password
LOG_LEVEL=INFO
EOF

基本身份验证故障排除

问题：“身份验证失败”

✅ 验证用户名和密码是否正确
✅ 检查帐户是否需要域： DOMAIN\username
✅ 确保Exchange服务器上启用了基本身份验证
✅ 请先尝试使用Outlook Web Access（OWA）验证凭据

问题：“连接被拒绝”

✅ 验证EWS_SERVER_URL是否正确
✅ 测试： curl https://mail.company.com/EWS/Exchange.asmx
✅ 检查防火墙/网络访问
✅ 尝试自动发现：设置 EWS_AUTODISCOVER=true

OAuth2身份验证（建议用于Office 365）

最适合：Office 365/Microsoft 365、生产环境、现代安全

快速设置（10分钟）

使用预先配置的模板:
```
cp .env.oauth2.example .env
```
在Azure AD中注册应用程序 （详见下文步骤）

更新 .env 使用Azure AD凭据:

EWS_SERVER_URL=https://outlook.office365.com/EWS/Exchange.asmx
EWS_EMAIL=user@company.com
EWS_AUTH_TYPE=oauth2
EWS_CLIENT_ID=your-azure-app-client-id
EWS_CLIENT_SECRET=your-azure-app-client-secret
EWS_TENANT_ID=your-azure-tenant-id

运行服务器:

docker run -d --env-file .env ghcr.io/azizmazrou/ews-mcp:latest

OAuth2安装程序（Azure AD）

在Azure AD中注册应用程序:
- 转到Azure门户→ Azure Active Directory→ 应用注册
- 点击“新建注册”
- 名称：“EWS MCP服务器”
- 支持的帐户类型：“仅此组织目录中的帐户”
- 点击“注册”
配置API权限:
- 转到“API权限”
- 点击“添加权限”
- 选择“Office 365 Exchange Online”
- 选择“应用程序权限”
- 添加： full_access_as_app 或特定权限，如：
  - Mail.ReadWrite
  - Calendars.ReadWrite
  - Contacts.ReadWrite
  - Tasks.ReadWrite
- 点击“授予管理员同意”
创建客户端密码:
- 转到“证书和机密”
- 点击“新建客户端密码”
- 描述：“EWS MCP机密”
- 过期：选择合适的持续时间
- 点击“添加” 立即复制机密值
获取ID:
- 客户端ID：从“概述”页面
- 租户ID：从“概述”页面
- 客户端密钥：从上述步骤3开始

更新.env:

EWS_CLIENT_ID=<your-client-id>
EWS_CLIENT_SECRET=<your-client-secret>
EWS_TENANT_ID=<your-tenant-id>

使用Claude Desktop

添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

使用GHCR的预构建图像（推荐）

{
  "mcpServers": {
    "ews": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/absolute/path/to/.env",
        "ghcr.io/azizmazrou/ews-mcp:latest"
      ]
    }
  }
}

使用本地构建的图像

{
  "mcpServers": {
    "ews": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--env-file",
        "/path/to/ews-mcp/.env",
        "ews-mcp-server"
      ]
    }
  }
}

使用本地Python（开发）

{
  "mcpServers": {
    "ews": {
      "command": "python",
      "args": ["-m", "src.main"],
      "cwd": "/path/to/ews-mcp",
      "env": {
        "EWS_EMAIL": "user@company.com",
        "EWS_AUTH_TYPE": "oauth2",
        "EWS_CLIENT_ID": "your-client-id",
        "EWS_CLIENT_SECRET": "your-secret",
        "EWS_TENANT_ID": "your-tenant"
      }
    }
  }
}

Docker镜像

预构建的Docker镜像会自动发布到GitHub容器注册表：

# Pull latest version
docker pull ghcr.io/azizmazrou/ews-mcp:latest

# Pull specific version
docker pull ghcr.io/azizmazrou/ews-mcp:1.0.0

# Pull development version
docker pull ghcr.io/azizmazrou/ews-mcp:main

可用标签：

latest -最新稳定版本
v*.*.* -特定版本（例如。， v1.0.0)
main -主分支机构的最新承诺
sha-<commit> -具体承诺

多平台支持：

linux/amd64 -x86_64系统
linux/arm64 -ARM64系统（苹果硅、ARM服务器）

可用工具

总计：9个类别的44个基础工具 （启用AI工具时最多48个）

联系人智能工具（3个工具）⭐ v2.1中的新功能

查找人员：跨GAL、电子邮件历史记录和域搜索联系人
- 具有智能重复数据删除功能的多源搜索
- 按通信频率和最近度排名
- 全域搜索（查找所有@example.com联系人）
- 阿拉伯语支持
get_通信_历史：分析与特定联系人的沟通
- 电子邮件统计（发送、接收、总计）
- 月度时间线可视化
- 从主题中提取主题
- 最近的电子邮件预览
分析网络：专业网络分析
- 按数量排列的顶级联系人
- 域/组织分组
- 休眠关系检测
- VIP联系人识别
- 综合概览模式

电子邮件工具（9个工具）

send_邮件：发送带有附件和CC/BCC的电子邮件(✅ 固定的： 附件现在实际发送！）
- ⭐ 新：通讯组列表支持-按名称发送到组（例如，“Team All”、“accounts”）
- 支持电子邮件地址、显示名称和通讯组列表
- 通讯组列表成员的自动扩展
阅读电子邮件：从指定文件夹读取电子邮件
搜索邮件：使用高级筛选器进行搜索
get_email_details：获取完整的电子邮件详细信息
删除电子邮件：删除或永久删除电子邮件
move_mail：在文件夹之间移动电子邮件
update_邮件: ⭐ 更新电子邮件属性（读取状态、标志、类别、重要性）
列表_附件: ⭐ 列出电子邮件的所有附件
下载_附件: ⭐ 下载电子邮件附件（base64或保存到文件）

附件工具（5个工具）🆕

列表_附件：列出电子邮件中的所有附件
下载_附件：下载base64格式的附件或保存到文件
添加附件：在电子邮件草稿中添加附件
删除附件：从电子邮件中删除附件
阅读附件: ⭐ 新从PDF、DOCX、XLSX、TXT文件中提取文本
- 支持阿拉伯语（UTF-8）文本
- 从文档中提取表格
- 大型PDF的页面限制
- 返回结构化文本内容

日历工具（6个工具）

创建_应用程序：安排与与会者的会议
get_calendar：检索日历事件
更新_预约：修改现有约会
删除_请求：取消约会/会议
回复会议：接受/拒绝会议邀请
check_可用性: ⭐ 获取用户在特定时间范围内的忙/闲信息

接触工具（6个工具）

create_contact：添加新联系人
search_contacts：按姓名/电子邮件查找联系人
get_contacts：列出所有联系人
update_contact：修改联系信息
删除联系人：删除联系人
resolve_names: ⭐ 将部分姓名/电子邮件解析为完整的联系信息

任务工具（5个工具）

创建任务：创建新任务
get_tasks：列出任务（按状态筛选）
update_task：修改任务详细信息
完成任务：将任务标记为已完成
删除任务：删除任务

搜索工具（1个工具）

高级搜索: ⭐ 使用过滤器跨文件夹进行复杂的多条件搜索

文件夹工具（1个工具）

list_folders: ⭐ 获取包含详细信息和项目计数的邮箱文件夹层次结构

测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_email_tools.py

# Run only unit tests (skip integration)
pytest -m "not integration"

发展

# Install development dependencies
pip install -r requirements-dev.txt

# Run linter
ruff check src/

# Format code
black src/

# Type checking
mypy src/

# Security check
bandit -r src/

建筑

EWS MCP Server
├── MCP Protocol Layer (stdio/SSE)
├── Tool Registry (Email, Calendar, Contacts, Tasks)
├── EWS Client (exchangelib wrapper)
├── Authentication (OAuth2/Basic/NTLM)
├── Middleware (Rate Limiting, Error Handling, Audit)
└── Exchange Web Services API

故障排除

看 docs/TROUBLESHOOTING.md 常见问题和解决方案。

文档

安装指南 -分步设置说明
部署指南 -部署到各种平台
GHCR指南 -使用预构建的Docker镜像
API 文档 -完整的工具参考
故障排除 -常见问题和解决方案
架构概述 -技术深潜

许可证

MIT许可证-有关详细信息，请参阅许可证文件

贡献

欢迎投稿！请在提交PR之前阅读投稿指南。

支持

对于问题和功能请求，请使用GitHub问题跟踪器。

更新日志

看更改日志.md 版本历史。

使用说明

EWS MCP服务器

特性

v2.1的新增功能🎯

多账户支持🔐

联系人智能工具（3个新工具）

统一联系人搜索

通信分析

网络智能

功能亮点

v2.0中的新增功能🚀

新工具（新增12个）

文件夹管理（4个工具）

增强型附件（2个工具）

高级搜索（2个工具）

外出（2个工具）

日历增强（1个工具）

电子邮件增强（1个工具）

功能亮点

快速开始

使用预构建的Docker镜像（最简单）

选项1：基本身份验证（最快设置-1分钟）

选项2:OAuth2身份验证（生产环境-Office 365）

从源头构建

本地开发

配置

基本身份验证（最简单-用于测试/本地）

快速设置（30秒）

使用预配置模板

交互式设置脚本

用于内部交换

基本身份验证故障排除

OAuth2身份验证（建议用于Office 365）

快速设置（10分钟）

OAuth2安装程序（Azure AD）

使用Claude Desktop

使用GHCR的预构建图像（推荐）

使用本地构建的图像

使用本地Python（开发）

Docker镜像

可用工具

联系人智能工具（3个工具）⭐ v2.1中的新功能

电子邮件工具（9个工具）

附件工具（5个工具）🆕

日历工具（6个工具）

接触工具（6个工具）

任务工具（5个工具）

搜索工具（1个工具）

文件夹工具（1个工具）

测试

发展

建筑

故障排除

文档

许可证

贡献

支持

更新日志

相关 MCP

时间服务器工具

Outlook日历管理工具

微软365 MCP服务器

iMCP：macOS 个人数据 MCP 服务器

Outlook会议调度服务

苹果提醒事项与日历 MCP 服务器