GmailMCPServer
Gmail MCP Server Swift SDK - 基于 MCP Swift SDK 的 Gmail API 集成。
功能
实现了 19 个 Gmail MCP 工具，覆盖邮件收发、标签管理、过滤器配置和批量操作。
工具列表
| 类别 | 工具 |
|---|---|
| 邮件 (6) | gmail_send_email, gmail_read_email, gmail_search_emails, gmail_modify_email, gmail_delete_email, gmail_download_attachment |
| 标签 (5) | gmail_list_labels, gmail_create_label, gmail_update_label, gmail_delete_label, gmail_get_or_create_label |
| 过滤器 (5) | gmail_create_filter, gmail_list_filters, gmail_get_filter, gmail_delete_filter, gmail_create_filter_from_template |
| 草稿 (1) | gmail_draft_email |
| 批量操作 (2) | gmail_batch_modify_emails, gmail_batch_delete_emails |
过滤器模板
gmail_create_filter_from_template 支持 6 种预设模板：
| 模板 | 说明 |
|---|---|
fromSender | 按发件人过滤 |
withSubject | 按主题关键词过滤 |
withAttachments | 过滤带附件的邮件 |
largeEmails | 过滤超过指定大小的邮件 |
containingText | 按正文内容过滤 |
mailingList | 过滤邮件列表 |
安装
Swift Package Manager
在 Package.swift 中添加依赖：
dependencies: [
.package(url: "https://github.com/zhan2333/gmail-mcp-server-swift.git", from: "1.0.0"),
]然后在 target 中添加：
.target(
name: "YourTarget",
dependencies: ["GmailMCPServer"]
),使用
基础用法
import GmailMCPServer
import MCP
// 1. 创建 Server
let server = GmailMCPServer(accessToken: "ya29.xxx")
// 2. 启动
try await server.start()
// 3. 获取工具列表
let tools = server.getTools()
print("Available tools: \(tools.count)") // 19
// 4. 执行工具 - 搜索邮件
let result = try await server.executeTool(
name: "gmail_search_emails",
arguments: [
"query": .string("from:github.com"),
"maxResults": .int(5)
]
)
// 5. 执行工具 - 发送邮件
let sendResult = try await server.executeTool(
name: "gmail_send_email",
arguments: [
"to": .array([.string("recipient@example.com")]),
"subject": .string("Hello from MCP"),
"body": .string("This email was sent via Gmail MCP Server.")
]
)带 Token 刷新的用法
let server = GmailMCPServer(
accessToken: "ya29.xxx",
refreshToken: "1//xxx",
clientId: "xxx.apps.googleusercontent.com",
clientSecret: "GOCSPX-xxx"
)
// 监听 Token 刷新事件，持久化新 Token
await server.client.updateOnTokenRefreshed { newToken in
KeychainManager.shared.saveGmailAccessToken(newToken)
}
try await server.start()集成到 MCP Manager (PeerBox)
// 注册到 MCPManager
MCPManager.shared.registerServer(server)配置
OAuth 2.0 凭证
从 Google Cloud Console 获取 OAuth 2.0 凭证，并启用 Gmail API。
// 方式 1: 仅 Access Token（无自动刷新）
let server = GmailMCPServer(accessToken: "ya29.xxx")
// 方式 2: 完整 OAuth 配置（支持自动刷新）
let config = GmailConfig(
accessToken: "ya29.xxx",
refreshToken: "1//xxx", // 可选
clientId: "xxx.apps", // 可选
clientSecret: "GOCSPX-xxx", // 可选
timeout: 30 // 可选，默认 30s
)
let server = GmailMCPServer(config: config)
// 方式 3: 从环境变量
// 需要设置 GMAIL_ACCESS_TOKEN，可选 GMAIL_REFRESH_TOKEN, GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET
let config = try GmailConfig.fromEnvironment()
let server = GmailMCPServer(config: config)Token 自动刷新
当 refreshToken、clientId、clientSecret 三者都提供时，API 客户端会在收到 401 响应时自动刷新 Token 并重试请求。
架构
Sources/GmailMCPServer/
├── GmailMCPServer.swift # 主服务器 (MCPServerProtocol)
├── GmailAPIClient.swift # HTTP 客户端 (actor, 自动 Token 刷新)
├── GmailConfig.swift # 配置
├── GmailEmailBuilder.swift # RFC 2822 邮件构造 + base64url 编码
├── Models/
│ ├── GmailError.swift # 错误类型
│ └── GmailModels.swift # API 响应模型
├── Tools/ # MCP 工具定义
│ ├── GmailTools.swift # 工具注册表 (19 个)
│ ├── MessageTools.swift # 邮件工具
│ ├── LabelTools.swift # 标签工具
│ ├── FilterTools.swift # 过滤器工具
│ ├── DraftTools.swift # 草稿工具
│ └── BatchTools.swift # 批量操作工具
└── Utils/
└── ValueExtensions.swift # MCP Value 扩展系统要求
- Swift 6.0+
- iOS 16.0+ / macOS 13.0+
依赖
- MCP Swift SDK (0.10.0+)
License
MIT