MCP 服务器

Gmail MCP Server

一个模型上下文协议服务器，它使 AI 助手能够与 Gmail 服务交互，通过 Google API 集成支持电子邮件操作、草稿管理和日历功能。 (Alternatively, a slightly more technical translation:) 一个模型上下文协议服务器，通过集成 Google API，使 AI 助手能够与 Gmail 服务进行交互，从而支持电子邮件操作、草稿管理和日历功能。

README

Gmail MCP 服务器

一个用于 Gmail API 集成的模型上下文协议 (MCP) 服务器实现，使 AI 助手能够与 Gmail 服务进行交互。

功能特性

核心功能

邮件操作
- 列出邮件，支持高级过滤
- 读取特定邮件的完整内容
- 创建并发送新邮件
草稿管理
- 创建新草稿
- 列出现有草稿
- 读取草稿内容
- 更新草稿内容和收件人
- 删除草稿
日历操作
- 列出即将到来的日历事件
- 读取详细的事件信息
- 创建新的日历事件
- 事件过滤和搜索
- 时区支持
- iOS 日历同步支持

搜索 & 过滤

Gmail 搜索查询支持
基于标签的过滤
可自定义的结果数量限制
日历事件搜索功能

安全性

Google OAuth2.0 集成
安全的凭据管理
刷新令牌处理
多范围授权支持

快速开始

前提条件

Node.js (v14 或更高版本)
npm (v6 或更高版本)
启用了 Gmail 和 Calendar API 的 Google Cloud Platform 帐户
具有适当范围的 OAuth 2.0 凭据

安装

克隆并安装依赖项：

git clone [repository-url]
cd gmail-mcp-server
npm install

配置环境：

# 创建 .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"

构建并运行：
```
npm run build
npm start
```

开发

可用脚本

npm run dev - 构建并运行，启用 watch 模式
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 接口

列出邮件

listEmails({
  maxResults?: number,    // 默认: 10
  query?: string,         // Gmail 搜索查询
  labelIds?: string[],    // 按标签过滤
  verbose?: boolean       // 包含详细信息
})

读取邮件

readEmail({
  messageId: string    // 要获取的邮件 ID
})

草稿操作

// 列出草稿
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[],         // 新抄送收件人
  bcc?: string[],         // 新密送收件人
  subject?: string,      // 新主题
  body?: string,         // 新正文内容
  isHtml?: boolean       // 内容类型标志
})

// 删除草稿
deleteDraft({
  draftId: string        // 要删除的草稿 ID
})

发送邮件

sendEmail({
  to: string[],
  subject: string,
  body: string,
  cc?: string[],
  bcc?: string[],
  isHtml?: boolean,
  draftId?: string    // 可选：发送现有草稿
})

日历操作

// 列出事件
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
})