Outlook MCP服务器

一个全面的模型上下文协议（MCP）服务器，提供对Microsoft Outlook电子邮件功能的编程访问。此服务器实现了完整的MCP协议规范，并公开了四个核心电子邮件操作，具有高级功能，包括性能优化、全面的错误处理和详细的日志记录。

🚀 特性

📧 完成电子邮件操作：列出、检索、搜索电子邮件和管理文件夹
🔌 MCP协议合规性：全面实施MCP协议，实现无缝集成
⚡ 性能优化：连接池、缓存、延迟加载和速率限制
🛡️ 稳健的错误处理：全面的错误分类和详细的诊断
📊 高级日志记录：具有性能指标和审计跟踪的结构化JSON日志记录
🔄 并发处理：高效处理多个同时进行的请求
🔧 广泛的配置：适用于所有环境的灵活配置选项
📚 综合文档：完整的API文档、示例和故障排除指南

📋 需求

系统要求

操作系统：Windows 10+（COM接口所需）
微软Outlook：2016或更高版本，已安装并配置
python：3.8或更高版本
记忆：建议使用4GB RAM
存储：2GB可用磁盘空间

依赖项

所有依赖项都列在 requirements.txt:

pywin32>=306 -Windows COM接口
mcp>=1.0.0 -模型上下文协议实现
asyncio -异步编程支持
pytest>=7.0.0 -测试框架
pytest-asyncio>=0.21.0 -异步测试支持

🛠️ 安装

快速开始

# 1. Clone the repository
git clone https://github.com/bitsplus1/EmailMCP.git
cd outlook-mcp-server

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

# 3. Test the installation
python main.py test

# 4. Start the HTTP server (recommended for testing)
python main.py http --config docker_config.json

# 5. Test with HTTP requests (see examples below)
curl -X POST http://192.168.1.100:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":"1","method":"list_inbox_emails","params":{"limit":5}}'

生产部署

对于生产环境，请使用增强的启动脚本：

# Start with production configuration
python start_server.py --config config/production.json

# Start as a service (Windows)
python start_server.py --service-mode

# Start with environment variables
export OUTLOOK_MCP_LOG_LEVEL=INFO
export OUTLOOK_MCP_LOG_DIR=/var/log/outlook-mcp
python start_server.py

# Install as Windows Service
python scripts/install_service.py install
python scripts/install_service.py start

环境配置

复制并自定义环境模板：

# Copy environment template
cp .env.example .env

# Edit configuration
notepad .env  # Windows

详细安装

有关包括系统设置、安全配置和部署选项在内的详细安装说明，请参阅 docs/SETUP_GUIDE.md.

🎯 用法

HTTP服务器模式（建议用于测试）

服务器支持HTTP模式，便于测试和集成：

# Run HTTP server with default configuration
python main.py http

# Run HTTP server with custom configuration
python main.py http --config docker_config.json

# HTTP server with custom host and port
python main.py http --host 0.0.0.0 --port 8080

# Test Outlook connection
python main.py test

MCP协议模式（适用于MCP客户端）

# Run as MCP server (stdio mode)
python main.py stdio

# Run with custom configuration
python main.py stdio --config my_config.json

# Interactive mode for development
python main.py interactive --log-level DEBUG

生产使用

# HTTP server for production (recommended)
python main.py http --config docker_config.json --host 0.0.0.0 --port 8080

# MCP stdio mode for MCP client integration
python main.py stdio --config production_config.json

# Service mode (no console output)
python start_server.py --service-mode --pid-file /var/run/outlook-mcp.pid

Windows服务管理

# Install service
python scripts/install_service.py install

# Start/stop service
python scripts/install_service.py start
python scripts/install_service.py stop

# Check service status
python scripts/install_service.py status

# Remove service
python scripts/install_service.py remove

健康监测

# Check server health
python -c "
import asyncio
from src.outlook_mcp_server.health import get_health_status
status = asyncio.run(get_health_status())
print(f'Status: {status.status}')
print(f'Outlook Connected: {status.outlook_connected}')
"

配置

创建和自定义配置：

# Generate default configuration file
python main.py create-config

配置示例(outlook_mcp_server_config.json):

{
  "log_level": "INFO",
  "log_dir": "logs",
  "max_concurrent_requests": 10,
  "request_timeout": 30,
  "outlook_connection_timeout": 10,
  "enable_performance_logging": true,
  "rate_limiting": {
    "enabled": true,
    "requests_per_minute": 100
  },
  "caching": {
    "enabled": true,
    "email_cache_ttl": 300,
    "max_cache_size_mb": 100
  },
  "security": {
    "allowed_folders": ["Inbox", "Sent Items"],
    "max_email_size_mb": 50
  }
}

📖 文档

完整的文档套件

API文档 -完整的API参考资料和示例
安装指南 -详细的安装和配置
使用示例 -实例和集成模式
故障排除指南 -常见问题和解决方案

API快速参考

可用的MCP方法

方法	说明	参数
`list_inbox_emails`	列出收件箱中的电子邮件（简单）	`unread_only`, `limit`
`list_emails`	列出来自特定文件夹的电子邮件	`folder_id`, `unread_only`, `limit`
`get_email`	按ID获取详细电子邮件	`email_id`
`search_emails`	按查询搜索电子邮件	`query`, `folder_id`, `limit`
`send_email`	通过Outlook发送电子邮件	`to_recipients`, `subject`, `body`等等。
`get_folders`	列出所有可用文件夹	无

HTTP API示例

启动HTTP服务器：

python main.py http --config docker_config.json

简单收件箱列表：

curl -X POST http://192.168.1.100:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "list_inbox_emails",
    "params": {
      "unread_only": true,
      "limit": 10
    }
  }'

获取特定电子邮件：

curl -X POST http://192.168.1.100:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "2",
    "method": "get_email",
    "params": {
      "email_id": "YOUR_EMAIL_ID_HERE"
    }
  }'

搜索电子邮件：

curl -X POST http://192.168.1.100:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "3",
    "method": "search_emails",
    "params": {
      "query": "meeting",
      "limit": 10
    }
  }'

发送电子邮件：

curl -X POST http://192.168.1.100:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "4",
    "method": "send_email",
    "params": {
      "to": ["recipient@example.com"],
      "subject": "Test Email",
      "body": "This is a test email sent via the MCP server."
    }
  }'

示例响应

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": [
    {
      "id": "AAMkADEx...",
      "subject": "Project Update",
      "sender": "john.doe@company.com",
      "received_time": "2024-01-15T10:30:00Z",
      "is_read": false,
      "has_attachments": true,
      "folder_name": "Inbox"
    }
  ]
}

🏗️ 建筑

系统架构

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Client    │◄──►│  MCP Protocol   │◄──►│ Request Router  │
│                 │    │    Handler      │    │                 │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                                                        │
                       ┌─────────────────┐    ┌─────────────────┐
                       │ Email Service   │◄──►│ Folder Service  │
                       │                 │    │                 │
                       └─────────────────┘    └─────────────────┘
                                │                       │
                       ┌─────────────────────────────────────────┐
                       │         Outlook Adapter                 │
                       │    (COM Interface Management)           │
                       └─────────────────────────────────────────┘
                                        │
                       ┌─────────────────────────────────────────┐
                       │        Microsoft Outlook               │
                       │         (COM Objects)                   │
                       └─────────────────────────────────────────┘

关键组件

MCP协议处理程序：管理协议合规性和消息格式
请求路由器：路由和验证传入请求
服务层：电子邮件和文件夹操作的业务逻辑
Outlook适配器：与Outlook的低级COM接口
表现层：缓存、连接池和优化
错误处理程序：全面的错误处理和恢复
记录系统：具有性能指标的结构化日志记录

🔧 发展

项目结构

outlook-mcp-server/
├── docs/                           # Complete documentation
│   ├── API_DOCUMENTATION.md        # API reference
│   ├── EXAMPLES.md                 # Usage examples
│   ├── SETUP_GUIDE.md             # Installation guide
│   └── TROUBLESHOOTING.md         # Problem resolution
├── src/outlook_mcp_server/         # Main source code
│   ├── adapters/                   # Outlook COM integration
│   ├── services/                   # Business logic layer
│   ├── protocol/                   # MCP protocol handling
│   ├── routing/                    # Request routing
│   ├── models/                     # Data models and exceptions
│   ├── logging/                    # Logging system
│   ├── performance/                # Performance optimizations
│   ├── server.py                   # Main server class
│   └── main.py                     # Entry point
├── tests/                          # Comprehensive test suite
├── examples/                       # Example scripts
├── main.py                         # Startup script
├── requirements.txt                # Dependencies
└── README.md                       # This file

运行测试

# Run all tests
python -m pytest tests/

# Run with coverage
python -m pytest tests/ --cov=src/outlook_mcp_server

# Run integration tests
python -m pytest tests/test_integration.py

# Run performance tests
python tests/run_integration_tests.py

开发设置

# Install development dependencies
pip install -r requirements.txt
pip install pytest pytest-cov pytest-asyncio

# Run in development mode
python main.py interactive --log-level DEBUG

# Enable performance profiling
python examples/profile_server.py

🚀 性能特点

优化技术

连接池：重用Outlook COM连接
智能高速缓存：TTL多级缓存
延迟加载：按需加载电子邮件内容
速率限制：防止系统过载
内存管理：自动清理和优化
并发处理：高效处理多个请求

性能监控

# Monitor performance in real-time
python main.py interactive --log-level INFO

# Generate performance reports
python scripts/analyze_performance.py logs/performance.log

# Memory usage monitoring
python examples/memory_monitor.py

🛡️ 安全和错误处理

安全特性

文件夹访问控制：限制对特定文件夹的访问
内容过滤：清理电子邮件内容和附件
速率限制：防止滥用和DoS攻击
输入验证：全面的参数验证
审计日志：完成所有业务的审计跟踪

错误处理

服务器提供全面的错误处理和详细的诊断：

验证错误：参数无效或请求格式错误
连接错误：Outlook连接问题
权限错误：违反访问控制
资源错误：缺少电子邮件或文件夹
性能错误：超时和费率限制

每个错误包括：

适当的MCP错误代码
详细的错误消息
调试上下文信息
建议的解决步骤

📊 监控和记录

日志记录功能

结构化JSON日志记录：机器可读日志格式
性能指标：请求时间和资源使用情况
审计跟踪：完整的操作历史记录
错误跟踪：带有上下文的详细错误信息
日志轮转：自动日志文件管理

日志分析

# View recent errors
findstr "ERROR" logs\outlook_mcp_server.log

# Analyze performance
python scripts/analyze_logs.py --performance

# Generate reports
python scripts/generate_report.py --daily

🆘 故障排除

快速诊断

# Test system health
python main.py test

# Check configuration
python main.py stdio --config my_config.json --test-connection

# Debug mode
python main.py interactive --log-level DEBUG

常见问题

问题	解决方案
找不到Outlook	确保已安装并注册Outlook
权限被拒绝	以管理员身份运行或检查Outlook安全设置
连接超时	增加 `outlook_connection_timeout` 在配置中
高内存使用率	减小缓存大小或启用内存管理

有关详细的故障排除，请参阅 docs/TROUBLESHOOTING.md.

🤝 贡献

我们欢迎捐款！请参阅我们的投稿指南：

分叉存储库
创建特征分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分行(git push origin feature/amazing-feature)
打开拉取请求

开发指南

遵循PEP 8风格指南
为新功能添加全面的测试
更新API变更文档
提交前确保所有测试通过
包含所有函数的类型提示

📄 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 支持

获取帮助

文档：检查 docs/ 目录
问题：报告错误
讨论：加入
电子邮件：联系方式support@your-org.com

企业支持

对于企业部署和商业支持：

专业安装配置
定制集成开发
优先支持和SLA
培训和咨询

联系人：enterprise@your-org.com

______________________________________________________________________

由...制作❤️ 由Outlook MCP服务器团队提供

*利用Microsoft Outlook和模型上下文协议的强大功能，使开发人员能够构建令人惊叹的电子邮件集成应用程序。*

Email MCP (Bitsplus1)

快速接入

详细介绍