gmail

Gmail Workspace MCP 服务

一个为 AI 助手提供 Gmail 集成的 MCP（Model Context Protocol）服务。支持个人 Gmail 账号（通过 OAuth2）和 Google Workspace 账号（通过支持全域委派的服务账号）。

功能

• 列出邮件会话：按标签筛选并检索邮件
• 获取邮件详情：获取完整邮件内容，包括正文和附件信息
• 搜索邮件：使用 Gmail 强大的查询语法进行搜索
• 管理邮件：标记为已读／未读、加星标／取消星标、归档、应用标签
• 创建草稿：撰写支持回复的邮件草稿
• 发送邮件：直接发送新邮件或回复，也可发送草稿
• 两种身份验证方式：个人账号使用 OAuth2，Google Workspace 使用服务账号

安装

npm install gmail-workspace-mcp-server

或使用 npx 直接运行：

npx gmail-workspace-mcp-server

身份验证

此服务支持两种身份验证模式。请选择与您的账号类型相匹配的模式。

选项 1：OAuth2（个人 Gmail 账号）

适用于个人 @gmail.com 账号，或没有 Workspace 管理员权限的任何 Google 账号。

前提条件

1. 前往 Google Cloud Console
2. 创建或选择一个项目
3. 启用 Gmail API
4. 配置 OAuth 同意屏幕：
   • 选择外部用户类型
   • 将自己添加为测试用户
   • 发布应用（在同意屏幕上点击“发布”），以防刷新令牌每 7 天过期。个人使用无需通过完整的 Google 验证。
5. 创建 OAuth 2.0 凭据：
   • 选择桌面应用作为应用类型
   • 重要：请在发布应用后创建新的凭据
6. 复制 Client ID 和 Client Secret

获取刷新令牌

运行内置的设置命令：

npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>

您也可以通过环境变量传入凭据：

GMAIL_OAUTH_CLIENT_ID=... GMAIL_OAUTH_CLIENT_SECRET=... npx gmail-workspace-mcp-server oauth-setup

端口冲突？ 如果端口 3000 已被占用，请指定其他端口：

PORT=3001 npx gmail-workspace-mcp-server oauth-setup <client_id> <client_secret>

桌面应用凭据会自动允许任何端口上的 http://localhost 重定向，因此无需额外配置 Google Cloud Console。

这将打开浏览器供您登录 Google，并输出刷新令牌。您只需执行一次此操作——只要 OAuth 同意屏幕已发布，刷新令牌就不会过期。

环境变量（OAuth2）

变量	必填	说明
GMAIL_OAUTH_CLIENT_ID	是	来自 Google Cloud Console 的 OAuth2 客户端 ID
GMAIL_OAUTH_CLIENT_SECRET	是	OAuth2 客户端密钥
GMAIL_OAUTH_REFRESH_TOKEN	是	设置脚本生成的刷新令牌
GMAIL_ENABLED_TOOLGROUPS	否	以逗号分隔的工具组列表（默认为全部）

Claude Desktop 配置（OAuth2）

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["gmail-workspace-mcp-server"],
      "env": {
        "GMAIL_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GMAIL_OAUTH_CLIENT_SECRET": "your-client-secret",
        "GMAIL_OAUTH_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

选项 2：服务账号（Google Workspace）

适用于域管理员可授予全域委派权限的 Google Workspace 组织。

前提条件

1. 前往 Google Cloud Console
2. 创建或选择一个项目
3. 启用 Gmail API
4. 创建一个已启用全域委派的服务账号
5. 在 Google Workspace Admin Console 中，授予服务账号以下范围的访问权限：
   • https://www.googleapis.com/auth/gmail.readonly（读取邮件）
   • https://www.googleapis.com/auth/gmail.modify（修改标签）
   • https://www.googleapis.com/auth/gmail.compose（创建草稿）
   • https://www.googleapis.com/auth/gmail.send（发送邮件）
6. 下载 JSON 密钥文件

环境变量（服务账号）

变量	必填	说明
GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL	是	服务账号邮箱地址
GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY	是	服务账号私钥（PEM 格式）
GMAIL_IMPERSONATE_EMAIL	是	要模拟的邮箱地址
GMAIL_ENABLED_TOOLGROUPS	否	要启用的工具组列表，以逗号分隔（默认：所有组）

你可以在服务账号 JSON 密钥文件中找到 client_email 和 private_key 的值。

Claude Desktop 配置（服务账号）

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["gmail-workspace-mcp-server"],
      "env": {
        "GMAIL_SERVICE_ACCOUNT_CLIENT_EMAIL": "[email protected]",
        "GMAIL_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nMIIE...\n-----END PRIVATE KEY-----",
        "GMAIL_IMPERSONATE_EMAIL": "[email protected]"
      }
    }
  }
}

注意： 对于私钥，你可以选择：

1. 直接使用密钥，并用 \n 表示换行（如上所示）
2. 从能够保留换行符的 shell 设置环境变量

工具组

该服务支持三个工具组，用于基于权限的访问控制：

组	包含的工具	风险等级
readonly	list_email_conversations、get_email_conversation、search_email_conversations、list_draft_emails	低
readwrite	所有只读工具 + change_email_conversation、upsert_draft_email	中
readwrite_external	所有读写工具 + send_email	高

默认情况下，所有工具组均已启用。若要限制访问，请设置 GMAIL_ENABLED_TOOLGROUPS 环境变量：

# Read-only access (no write/send capabilities)
GMAIL_ENABLED_TOOLGROUPS=readonly

# Read and write, but no external sending
GMAIL_ENABLED_TOOLGROUPS=readwrite

# Full access including sending emails (default)
GMAIL_ENABLED_TOOLGROUPS=readwrite_external

安全提示： send_email 工具属于单独的 readwrite_external 组，因为它可以向外部发送邮件，风险高于修改标签或创建草稿等内部操作。

可用工具

list_email_conversations

列出 Gmail 邮件会话，并可选择使用筛选条件。

参数：

• count（number，可选）：要返回的邮件数量（默认：10，最大：100）
• labels（string，可选）：用于筛选的标签 ID，以逗号分隔（默认："INBOX"）
• sort_by（string，可选）：排序顺序——"recent"（最新优先）或 "oldest"（默认：recent）
• after（string，可选）：仅返回此日期时间之后的邮件，不包含此时间（ISO 8601 UTC，例如："2024-01-15T14:30:00Z"）
• before（string，可选）：仅返回此日期时间之前的邮件，不包含此时间（ISO 8601 UTC，例如："2024-01-15T14:30:00Z"）

示例：

{
  "count": 20,
  "labels": "INBOX,STARRED",
  "after": "2024-01-15T00:00:00Z",
  "before": "2024-01-20T23:59:59Z"
}

get_email_conversation

通过邮件 ID 获取特定邮件的完整内容。

参数：

• email_id（string，必填）：邮件的唯一标识符

示例：

{
  "email_id": "18abc123def456"
}

search_email_conversations

使用 Gmail 强大的查询语法搜索邮件。

参数：

• query（string，必填）：Gmail 搜索查询（例如："from:[email protected]"、"is:unread"、"subject:meeting"）
• count（number，可选）：要返回的最大结果数（默认：10，最大：100）

示例：

{
  "query": "from:[email protected] is:unread",
  "count": 20
}

change_email_conversation

修改邮件标签和状态（已读/未读、加星标、已归档）。

参数：

• email_id（string，必填）：要修改的邮件 ID
• status（string，可选）："read"、"unread" 或 "archived"
• is_starred（boolean，可选）：为邮件加上或取消星标
• labels（string，可选）：要添加的标签，以逗号分隔
• remove_labels（string，可选）：要移除的标签，以逗号分隔

示例：

{
  "email_id": "18abc123def456",
  "status": "read",
  "is_starred": true
}

list_draft_emails

列出 Gmail 中的草稿邮件，可选按会话线程筛选。

参数：

• count（number，可选）：要返回的草稿数量上限（默认值：10，最大值：100）
• thread_id（string，可选）：按会话线程 ID 筛选草稿

示例：

{
  "thread_id": "18abc123def456"
}

upsert_draft_email

创建、更新或删除草稿邮件。也可选择将其作为对现有会话的回复。

参数：

• draft_id（string，可选）：要更新或删除的现有草稿 ID（省略则创建新草稿）
• delete（boolean，可选）：设为 true 以删除 draft_id 指定的草稿。删除时会忽略所有其他参数
• to（string，创建/更新时必需）：收件人电子邮件地址
• subject（string，创建/更新时必需）：邮件主题
• plaintext_body（string）：纯文本正文内容（创建/更新时，必须至少提供 plaintext_body 或 html_body 其中之一）
• html_body（string）：用于富文本格式的 HTML 正文内容（创建/更新时，必须至少提供 plaintext_body 或 html_body 其中之一）
• cc（string，可选）：抄送收件人
• bcc（string，可选）：密送收件人
• thread_id（string，可选）：回复所用的线程 ID
• reply_to_email_id（string，可选）：要回复的邮件 ID（设置 References/In-Reply-To 标头）

创建/更新时，必须至少提供 plaintext_body 或 html_body 其中之一。如果两者都提供，则会发送包含这两个版本的多部分邮件。

示例（创建新草稿）：

{
  "to": "[email protected]",
  "subject": "Meeting Follow-up",
  "plaintext_body": "Thanks for the meeting today!"
}

示例（更新现有草稿）：

{
  "draft_id": "r123456789",
  "to": "[email protected]",
  "subject": "Meeting Follow-up (revised)",
  "html_body": "<p>Thanks for the meeting today! Check out <a href=\"https://example.com/notes\">the notes</a>.</p>"
}

示例（删除草稿）：

{
  "draft_id": "r123456789",
  "delete": true
}

send_email

直接发送邮件或发送现有草稿。

参数：

• to（string，视情况而定）：收件人电子邮件（除非从草稿发送，否则必需）
• subject（string，视情况而定）：邮件主题（除非从草稿发送，否则必需）
• plaintext_body（string）：纯文本正文内容（除非发送草稿，否则必须至少提供 plaintext_body 或 html_body 其中之一）
• html_body（string）：用于富文本格式的 HTML 正文内容（除非发送草稿，否则必须至少提供 plaintext_body 或 html_body 其中之一）
• cc（string，可选）：抄送收件人
• bcc（string，可选）：密送收件人
• from_draft_id（string，可选）：按 ID 发送现有草稿
• thread_id（string，可选）：回复所用的线程 ID
• reply_to_email_id（string，可选）：要回复的邮件 ID

示例（纯文本邮件）：

{
  "to": "[email protected]",
  "subject": "Hello",
  "plaintext_body": "This is a test email."
}

示例（HTML 邮件）：

{
  "to": "[email protected]",
  "subject": "Hello",
  "html_body": "<p>Check out <a href=\"https://example.com\">our website</a> for more details.</p>"
}

示例（发送草稿）：

{
  "from_draft_id": "r123456789"
}

开发

设置

# Install dependencies
npm run install-all

# Build
npm run build

# Run in development mode
npm run dev

测试

# Run functional tests
npm test

# Run integration tests
npm run test:integration

# Run manual tests (requires credentials)
npm run test:manual

许可证

MIT