Gmail MCP 服务器
用于 Gmail API 集成的模型上下文协议 (MCP) 服务器实现，使 AI 助手能够与 Gmail 服务进行交互。
特征
核心功能
- 电子邮件操作
- 使用高级过滤功能列出电子邮件
- 阅读特定电子邮件的完整内容
- 创建和发送新电子邮件
- 草稿管理
- 创建新草稿
- 列出现有草稿
- 阅读草稿内容
- 更新草稿内容和收件人
- 删除草稿
- 日历操作
- 列出即将发生的日历事件
- 阅读详细的活动信息
- 创建新的日历事件
- 事件过滤和搜索
- 时区支持
- iOS 日历同步支持
搜索和过滤
- Gmail 搜索查询支持
- 基于标签的过滤
- 可定制的结果限制
- 日历事件搜索功能
安全
- Google OAuth2.0 集成
- 安全凭证管理
- 刷新令牌处理
- 多范围授权支持
快速入门
先决条件
- Node.js（v14 或更高版本）
- npm（v6 或更高版本）
- 已启用 Gmail 和日历 API 的 Google Cloud Platform 帐户
- 具有适当范围的 OAuth 2.0 凭据
安装
- 克隆并安装依赖项：
git clone [repository-url]
cd gmail-mcp-server
npm install
- 配置环境：
# Create .env file
cp .env.example .env
# Add your credentials:
GOOGLE_CLIENT_ID="your_client_id"
GOOGLE_CLIENT_SECRET="your_client_secret"
REDIRECT_URI="http://localhost:4100/code"
GOOGLE_REFRESH_TOKEN="your_refresh_token"
- 构建并运行：
发展
可用脚本
npm run dev - 使用监视模式构建并运行npm run build构建项目npm run clean - 清理构建产物npm run watch - 观察变化
项目结构
gmail-mcp-server/
├── src/
│ ├── config/ # Configuration and setup
│ ├── services/ # Core business logic
│ │ ├── gmail/ # Gmail services
│ │ └── calendar/ # Calendar services
│ ├── tools/ # MCP tool implementations
│ │ ├── calendar/ # Calendar tools
│ │ ├── drafts/ # Draft management tools
│ │ └── messages/ # Email tools
│ ├── types/ # TypeScript definitions
│ └── index.ts # Server entry point
├── dist/ # Compiled JavaScript
└── tests/ # Test files (pending)
API接口
列出消息
listEmails({
maxResults?: number, // Default: 10
query?: string, // Gmail search query
labelIds?: string[], // Filter by labels
verbose?: boolean // Include details
})
阅读消息
readEmail({
messageId: string // Message ID to fetch
})
草案操作
// List Drafts
listDrafts({
maxResults?: number, // Default: 10
query?: string, // Search query
verbose?: boolean // Include details
})
// Read Draft
readDraft({
draftId: string // Draft ID to fetch
})
// Create Draft
draftEmail({
to: string[],
subject: string,
body: string,
cc?: string[],
bcc?: string[],
isHtml?: boolean
})
// Update Draft
updateDraft({
draftId: string, // Draft ID to update
to?: string[], // New recipients
cc?: string[], // New CC recipients
bcc?: string[], // New BCC recipients
subject?: string, // New subject
body?: string, // New body content
isHtml?: boolean // Content type flag
})
// Delete Draft
deleteDraft({
draftId: string // Draft ID to delete
})
发送电子邮件
sendEmail({
to: string[],
subject: string,
body: string,
cc?: string[],
bcc?: string[],
isHtml?: boolean,
draftId?: string // Optional: send existing draft
})
日历操作
// List Events
listEvents({
maxResults?: number, // Default: 25
timeMin?: string, // Start time (ISO 8601)
timeMax?: string, // End time (ISO 8601)
query?: string, // Text search term
timeZone?: string // Default: Australia/Brisbane
})
// Read Event Details
readEvent({
eventId: string, // Event ID to fetch details
timeZone?: string // Default: Australia/Brisbane
})
// Create Event
createEvent({
summary: string, // Event title
start: {
dateTime: string, // ISO 8601 start time
timeZone?: string // Start time timezone
},
end: {
dateTime: string, // ISO 8601 end time
timeZone?: string // End time timezone
},
description?: string, // Optional event description
location?: string, // Optional event location
attendees?: Array<{ // Optional attendees
email: string,
displayName?: string,
optional?: boolean
}>,
status?: 'confirmed' | 'tentative' | 'cancelled',
sendNotifications?: boolean
})
错误处理
服务器实现了全面的错误处理：
- 身份验证失败
- API 速率限制
- 无效请求
- 网络问题
- 日历同步问题
- 事件 ID 验证
- 时区验证
贡献
请参阅CONTRIBUTING.md了解指南。
变更日志
请参阅CHANGELOG.md了解版本历史和更新。
路线图
请参阅Backlog.md了解计划的功能和改进。
执照
MIT 许可证 - 详情请参阅许可证。