zacco16
服务介绍
Gmail MCP 服务器
这是一个用于Gmail API集成的模型上下文协议（MCP）服务器实现，使AI助手能够与Gmail服务进行交互。
功能
核心功能
- 邮件操作
- 列出带有高级过滤器的邮件
- 阅读包含完整内容的特定邮件
- 创建并发送新邮件
- 草稿管理
- 创建新草稿
- 列出现有草稿
- 阅读草稿内容
- 更新草稿内容和收件人
- 删除草稿
- 日历操作
- 列出即将到来的日历事件
- 阅读详细的事件信息
- 创建新的日历事件
- 事件过滤和搜索
- 时区支持
- iOS日历同步支持
搜索与过滤
- 支持Gmail搜索查询
- 基于标签的过滤
- 可自定义的结果限制
- 日历事件搜索能力
安全性
- Google OAuth2.0集成
- 安全凭证管理
- 刷新令牌处理
- 多范围授权支持
快速开始
先决条件
- Node.js (v14或更高版本)
- npm (v6或更高版本)
- 启用了Gmail和Calendar APIs的Google Cloud Platform账户
- 具有适当范围的OAuth 2.0凭据
安装
-
克隆并安装依赖项：
bash
git clone [repository-url]
cd gmail-mcp-server
npm install -
配置环境：
bash创建.env文件
cp .env.example .env
添加您的凭据：
GOOGLE_CLIENT_ID="your_client_id"
GOOGLE_CLIENT_SECRET="your_client_secret"
REDIRECT_URI="http://localhost:4100/code"
GOOGLE_REFRESH_TOKEN="your_refresh_token" -
构建并运行：
bash
npm run build
npm start
开发
可用脚本
npm run dev- 使用监视模式构建并运行npm run build- 构建项目npm run clean- 清理构建产物npm run watch- 监视更改
项目结构
gmail-mcp-server/
├── src/
│ ├── config/ # 配置和设置
│ ├── services/ # 核心业务逻辑
│ │ ├── gmail/ # Gmail服务
│ │ └── calendar/ # 日历服务
│ ├── tools/ # MCP工具实现
│ │ ├── calendar/ # 日历工具
│ │ ├── drafts/ # 草稿管理工具
│ │ └── messages/ # 邮件工具
│ ├── types/ # TypeScript定义
│ └── index.ts # 服务器入口点
├── dist/ # 编译后的JavaScript
└── tests/ # 测试文件（待定）
API接口
列出消息
typescript
listEmails({
maxResults?: number, // 默认：10
query?: string, // Gmail搜索查询
labelIds?: string[], // 按标签过滤
verbose?: boolean // 包含详细信息
})
读取消息
typescript
readEmail({
messageId: string // 要获取的消息ID
})
草稿操作
typescript
// 列出草稿
listDrafts({
maxResults?: number, // 默认：10
query?: string, // 搜索查询
verbose?: boolean // 包含详细信息
})
// 读取草稿
readDraft({
draftId: string // 要获取的草稿ID
})
// 创建草稿
draftEmail({
to: string[],
subject: string,
body: string,
cc?: string[],
bcc?: string[],
isHtml?: boolean
})
// 更新草稿
updateDraft({
draftId: string, // 要更新的草稿ID
to?: string[], // 新收件人
cc?: string[], // 新CC收件人
bcc?: string[], // 新BCC收件人
subject?: string, // 新主题
body?: string, // 新正文内容
isHtml?: boolean // 内容类型标志
})
// 删除草稿
deleteDraft({
draftId: string // 要删除的草稿ID
})
发送邮件
typescript
sendEmail({
to: string[],
subject: string,
body: string,
cc?: string[],
bcc?: string[],
isHtml?: boolean,
draftId?: string // 可选：发送现有草稿
})#### 日历操作
typescript
// 列出事件
listEvents({
maxResults?: number, // 默认: 25
timeMin?: string, // 开始时间 (ISO 8601)
timeMax?: string, // 结束时间 (ISO 8601)
query?: string, // 文本搜索词
timeZone?: string // 默认: Australia/Brisbane
})
// 读取事件详情
readEvent({
eventId: string, // 要获取详情的事件ID
timeZone?: string // 默认: Australia/Brisbane
})
// 创建事件
createEvent({
summary: string, // 事件标题
start: {
dateTime: string, // ISO 8601 开始时间
timeZone?: string // 开始时间时区
},
end: {
dateTime: string, // ISO 8601 结束时间
timeZone?: string // 结束时间时区
},
description?: string, // 可选的事件描述
location?: string, // 可选的事件地点
attendees?: Array<{ // 可选的参与者
email: string,
displayName?: string,
optional?: boolean
}>,
status?: confirmed | tentative | cancelled , // 状态：已确认 | 待定 | 已取消
sendNotifications?: boolean // 是否发送通知
})
错误处理
服务器实现了全面的错误处理，包括：
- 认证失败
- API 速率限制
- 无效请求
- 网络问题
- 日历同步问题
- 事件ID验证
- 时区验证
贡献指南
请参阅 CONTRIBUTING.md 获取指南。
更新日志
请参阅 CHANGELOG.md 查看版本历史和更新。
道路图
请参阅 Backlog.md 查看计划的功能和改进。
许可证
MIT 许可证 - 详情见 LICENSE。
