Email Processing MCP Server

电子邮件处理 MCP 服务

一个跨平台 MCP 服务，可处理 Microsoft Outlook 电子邮件，使用 Ollama 生成向量嵌入，并提供语义搜索功能。适用于 Windows、macOS，以及通过 Microsoft Graph API 支持的任何平台。

该服务符合 Model Context Protocol（MCP）2025-06-18 规范，并使用官方 MCP SDK。

功能

核心能力

• 处理 Outlook 电子邮件，并按日期范围筛选
• 使用 SQLite 数据库存储电子邮件，并妥善管理连接
• 使用 Ollama（nomic-embed-text）生成向量嵌入
• 通过 MongoDB 向量存储对电子邮件内容进行语义搜索
• 支持多个邮箱和多个账户
• 支持收件箱、已发送邮件，以及可选的已删除邮件文件夹

跨平台支持

• Windows：通过 pywin32 原生自动化操作 Outlook COM
• macOS：通过 AppleScript 与 Outlook for Mac 集成
• 任何平台：通过 Microsoft Graph API 云端访问（Windows、macOS、Linux、容器）

符合 MCP 2025-06-18 规范

• 结构化工具结果：工具返回类型正确且经过验证的 Pydantic 模型
• HTTP 传输：支持 STDIO 和 HTTP（Streamable HTTP）传输
• 协议协商：在握手期间声明协议版本
• 增强元数据：提供工具标题和描述，以便更好地集成到 UI

可用工具（12+）

类别	工具
电子邮件处理	process_emails
搜索与分析	search_emails、analyze_email_sentiment、find_actionable_items
数据导出	export_email_data（CSV、JSON、HTML、Excel）
文件夹管理	list_outlook_folders、get_folder_statistics、organize_emails_by_rules
联系人管理	extract_contacts
统计	get_email_statistics、check_data_consistency

前置条件

必需（所有平台）

• Python 3.10 或更高版本
• 本地运行的 Ollama，并已安装 nomic-embed-text 模型
• MongoDB 服务（用于存储嵌入）

平台特定要求

平台	要求
Windows	已安装 Microsoft Outlook + pywin32
macOS	已安装 Microsoft Outlook for Mac
Graph API	已注册 Azure AD 应用，并具有 Mail.Read 权限

安装

1. 安装 uv（如果尚未安装）

pip install uv

2. 创建并激活虚拟环境

uv venv .venv

# Windows
.venv\Scripts\activate

# macOS/Linux
source .venv/bin/activate

3. 安装依赖项

核心安装（必需）：

uv pip install -e .

平台特定的额外组件：

# Windows (adds pywin32 for COM automation)
uv pip install -e ".[windows]"

# Graph API support (cross-platform cloud access)
uv pip install -e ".[graph]"

# All optional dependencies
uv pip install -e ".[all]"

4. 安装 Ollama 嵌入模型

ollama pull nomic-embed-text

5.（仅限 Graph API）注册 Azure AD 应用程序

如果使用 Microsoft Graph API，需要在 Azure AD 中注册应用程序：

1. 前往 Azure Portal → Azure Active Directory → App registrations
2. 点击“New registration”
3. 为应用命名，并选择“Accounts in this organizational directory only”
4. 创建后，记下 Application (client) ID 和 Directory (tenant) ID
5. 前往“Certificates & secrets” → “New client secret” → 记下密钥值
6. 前往“API permissions” → “Add a permission” → “Microsoft Graph” → “Application permissions”
7. 添加：Mail.Read、User.Read.All（用于发现多个账户）
8. 点击“Grant admin consent”

配置

将服务添加到 Claude for Desktop 配置文件中：

• Windows：%APPDATA%\Claude\claude_desktop_config.json
• macOS：~/Library/Application Support/Claude/claude_desktop_config.json

环境变量

变量	描述	必填
MONGODB_URI	MongoDB 连接字符串	是
SQLITE_DB_PATH	SQLite 数据库文件路径	是
EMBEDDING_BASE_URL	Ollama 服务 URL（默认值：http://localhost:11434）	否
EMBEDDING_MODEL	嵌入模型名称（默认值：nomic-embed-text）	否
COLLECTION_NAME	MongoDB 集合名称	是
PROCESS_DELETED_ITEMS	是否处理 Deleted Items 文件夹（默认值："false"）	否
OUTLOOK_PROVIDER	提供程序：auto、windows、mac、graph（默认值："auto"）	否
LOCAL_TIMEZONE	日期使用的时区（默认值："UTC"，例如："America/Chicago"）	否

Graph API 变量（当 OUTLOOK_PROVIDER=graph 时必填）：

变量	描述
GRAPH_CLIENT_ID	Azure AD 应用程序客户端 ID
GRAPH_CLIENT_SECRET	Azure AD 客户端密钥
GRAPH_TENANT_ID	Azure AD 租户 ID
GRAPH_USER_EMAILS	邮箱：逗号分隔的列表，或使用 "All" 自动发现

---

Windows 配置（COM 自动化）

通过 pywin32 使用原生 Outlook COM 自动化。

{
  "mcpServers": {
    "outlook-email": {
      "command": "C:/path/to/.venv/Scripts/python",
      "args": ["C:/path/to/src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "SQLITE_DB_PATH": "C:\\path\\to\\data\\emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "windows",
        "LOCAL_TIMEZONE": "America/Chicago"
      }
    }
  }
}

macOS 配置（AppleScript）

使用 AppleScript 与 Outlook for Mac 通信。

{
  "mcpServers": {
    "outlook-email": {
      "command": "/path/to/.venv/bin/python",
      "args": ["/path/to/src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP?authSource=admin",
        "SQLITE_DB_PATH": "/path/to/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "mac",
        "LOCAL_TIMEZONE": "America/Los_Angeles"
      }
    }
  }
}

Graph API 配置（跨平台）

只要具有 Azure AD 凭据，即可在任何平台上使用。支持单个或多个邮箱。

单个邮箱或指定邮箱：

{
  "mcpServers": {
    "outlook-email": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP",
        "SQLITE_DB_PATH": "/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "graph",
        "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
        "GRAPH_CLIENT_SECRET": "your-client-secret",
        "GRAPH_TENANT_ID": "your-tenant-id",
        "GRAPH_USER_EMAILS": "[email protected],[email protected]"
      }
    }
  }
}

租户中的所有邮箱（自动发现）：

{
  "mcpServers": {
    "outlook-email": {
      "command": "python",
      "args": ["src/mcp_server.py"],
      "env": {
        "MONGODB_URI": "mongodb://localhost:27017/MCP",
        "SQLITE_DB_PATH": "/data/emails.db",
        "EMBEDDING_BASE_URL": "http://localhost:11434",
        "EMBEDDING_MODEL": "nomic-embed-text",
        "COLLECTION_NAME": "outlook-emails",
        "OUTLOOK_PROVIDER": "graph",
        "GRAPH_CLIENT_ID": "your-azure-ad-client-id",
        "GRAPH_CLIENT_SECRET": "your-client-secret",
        "GRAPH_TENANT_ID": "your-tenant-id",
        "GRAPH_USER_EMAILS": "All"
      }
    }
  }
}

提供程序自动检测

当 OUTLOOK_PROVIDER 设置为 auto（默认值）时，服务会自动选择最佳提供程序：

平台	自动选择的提供程序
Windows	windows（COM 自动化）
macOS	mac（AppleScript）
Linux/其他	graph（需要配置 Azure AD）

HTTP 传输（符合 2025-06-18 规范）

使用 HTTP 传输时，添加 --http 标志运行服务：

python src/mcp_server.py --http

这将在 http://localhost:8000/mcp 启动服务，并全面符合 2025-06-18 协议规范，包括：

• 协议版本协商
• 结构化输出架构
• HTTP 标头验证
• 正确的错误处理

HTTP 传输支持有状态和无状态两种运行模式。

---

可用工具

1. process_emails

处理指定日期范围内的电子邮件，并返回结构化结果：

输入：

{
  "start_date": "2024-01-01",    # ISO format date (YYYY-MM-DD)
  "end_date": "2024-02-15",      # ISO format date (YYYY-MM-DD)
  "mailboxes": ["All"]           # List of mailbox names or ["All"] for all mailboxes
}

输出（结构化）：

{
  "success": true,
  "processed_count": 150,
  "retrieved_count": 200,
  "stored_count": 180,
  "failed_count": 20,
  "message": "Successfully processed 150 emails (retrieved: 200, stored: 180, failed: 20)",
  "error": null
}

该工具将：

1. 连接到指定的 Outlook 邮箱
2. 从 Inbox 和 Sent Items 文件夹中检索电子邮件（如果启用，还会检索 Deleted Items 中的邮件）
3. 将电子邮件存储在 SQLite 数据库中
4. 使用 Ollama 生成嵌入向量
5. 将嵌入向量存储在 MongoDB 中，以便进行语义搜索
6. 返回包含详细统计信息的结构化结果

在 Claude 中的示例用法

"Process emails from February 1st to February 17th from all mailboxes"

架构

基于提供程序的连接器设计

该服务采用基于提供程序的抽象层，实现跨平台电子邮件访问：

src/connectors/
├── base.py               # OutlookConnectorBase (abstract interface)
├── factory.py            # create_connector() with auto-detection
├── windows_connector.py  # Windows COM via pywin32
├── mac_connector.py      # macOS AppleScript via osascript
└── graph_connector.py    # Microsoft Graph API (cross-platform)

所有连接器都实现相同的接口，无论平台如何，均返回标准化的 EmailMetadata 对象。

双数据库架构

该服务采用混合存储方式：

SQLite 数据库：

• 主要的电子邮件存储和元数据
• 全文搜索功能
• 处理状态跟踪
• 日期范围和文件夹筛选
• 快速结构化查询

MongoDB：

• 存储向量嵌入（768 维）
• 语义相似度搜索
• 将元数据与嵌入向量一同存储
• 支持 AI 驱动的搜索

错误处理

该服务会针对常见问题提供详细的错误消息：

• 日期格式无效
• 与 Outlook 的连接问题
• MongoDB 错误
• 嵌入生成失败时的重试逻辑
• SQLite 存储错误
• Ollama 服务连接问题及自动重试

资源管理

服务器实现了适当的资源管理，以避免出现问题：

• 数据库连接（SQLite 和 MongoDB）在服务器运行期间保持打开，以避免出现“Cannot operate on a closed database”错误
• 仅在服务器关闭时使用 atexit 处理程序关闭连接
• 使用析构函数和上下文管理器作为后备机制，确保对象被垃圾回收时关闭连接
• 连接管理旨在平衡资源使用与运行可靠性
• 对 Ollama 等外部服务采用稳健的重试逻辑，以应对临时连接问题

符合 MCP 2025-06-18 规范

此服务器已升级为符合 MCP 2025-06-18 规范：

协议功能

• 协议版本：握手期间声明 protocolVersion: "2025-06-18"
• 结构化输出：所有工具均返回经过类型检查和验证的 Pydantic 模型
• HTTP 传输：支持 Streamable HTTP，并进行适当的标头验证
• 工具元数据：增强工具描述，包含标题和架构
• 错误处理：返回结构化错误响应和详细信息

传输支持

• STDIO：传统的标准输入/标准输出通信（默认）
• HTTP：在 localhost:8000/mcp 上提供 Streamable HTTP，并进行标头验证
• 协议标头：验证 MCP-Protocol-Version 和 Origin 标头
• 单消息 JSON-RPC：根据 2025-06-18 规范，不支持批量请求

结构化输出

process_emails 工具会返回结构化的 ProcessEmailsResult，包含：

• success：表示操作是否成功的布尔值
• processed_count：成功处理的邮件数量
• retrieved_count：从 Outlook 获取的邮件总数
• stored_count：存储在 SQLite 中的邮件数量
• failed_count：处理失败的邮件数量
• message：人类可读的状态消息
• error：操作失败时的错误详情

安全说明

• 服务器仅处理指定邮箱中的邮件
• 所有数据均存储在本地（SQLite）和 MongoDB 中
• 除本地 Ollama 服务外，不会调用外部 API（使用该提供方时也会调用 Microsoft Graph）
• 处理邮件前需要用户明确批准
• 不会通过 MCP 接口暴露任何敏感邮件数据
• 出于安全考虑，HTTP 传输仅绑定到 localhost
• Graph API 使用 Azure AD 的 OAuth 2.0 客户端凭据流
• 妥善保管 Azure AD 凭据（使用环境变量，而不要写入代码）

调试

如果遇到问题：

1. 确认邮件已成功处理（检查 process_emails 响应）
2. 确保 Ollama 服务正在运行，以生成嵌入
3. 检查 SQLite 数据库是否可访问
4. 确认 MongoDB 连接正常
5. 使用 check_data_consistency 工具验证 SQLite/MongoDB 同步情况

特定平台的调试

Windows：

• 确保 Outlook 正在运行且可访问
• 检查是否已安装 pywin32：pip show pywin32
• 验证 COM 自动化是否正常：python -c "import win32com.client; print('OK')"

macOS：

• 确保已安装 Outlook for Mac（而不只是“New Outlook”网页应用）
• 测试 AppleScript 访问：osascript -e 'tell application "Microsoft Outlook" to get name'
• 在“系统偏好设置”→“安全性与隐私”→“自动化”中授予 Terminal/IDE 权限

Graph API：

• 确认 Azure AD 应用具有正确的权限（Mail.Read、User.Read.All）
• 检查是否已授予管理员同意
• 测试令牌获取：凭据会在启动时记录
• 确认 GRAPH_USER_EMAILS 设置正确（“All”或以逗号分隔的电子邮件地址）

平台限制

平台	限制
Windows	需要 Outlook 桌面应用正在运行
macOS	“New Outlook”的 AppleScript 支持可能有限；可使用 Graph API 作为备用方案
Graph API	需要配置 Azure AD；日期范围最多为 30 天
所有平台	每次请求的处理日期范围最多为 30 天

即将推出的功能

• 使用大模型总结邮件
• 自动对邮件进行分类
• 可自定义的邮件报告
• 使用 Outlook 起草邮件回复
• Outlook 规则建议
• 扩展数据库选项，集成 Neo4j 和 ChromaDB