Gmail Multi MCP

Gmail多账户MCP服务器

一个模型上下文协议（MCP）服务器，使Claude Desktop能够通过安全的OAuth 2.0身份验证与多个Gmail帐户进行交互。

特性

• 多账户支持 -添加、删除和在多个Gmail帐户之间切换
• 默认帐户管理 -设置默认帐户以快速访问
• 发送邮件 -纯文本、HTML、多部分、带CC/BCC和文件附件
• 搜索电子邮件 -使用Gmail强大的搜索运算符（from、subject、has:attachment、newer_than、is:unread等）
• 阅读电子邮件 -使用附件元数据检索完整的电子邮件内容
• 电子邮件修改 -修改标签、标记为已读/未读、删除邮件
• 批量操作 -批量修改标签或删除具有可配置批量大小的消息
• 附件支持 -发送附件并下载它们，并进行路径安全验证
• 标签管理 -创建、更新、删除和列出Gmail标签
• 过滤器管理 -使用预构建的模板创建、列出、获取、删除过滤器
• 主题回复 -使用“回复/引用”标题回复电子邮件
• 安全OAuth 2.0身份验证 -未存储密码；令牌自动刷新
• 安全加固 -MIME头注入防止、敏感路径阻塞、路径遍历保护
• MCP检查员 -用于测试和调试的内置开发工具

快速开始

1. 设置谷歌云控制台 （参见 详细步骤如下):

- 创建项目并启用Gmail API - 创建OAuth 2.0桌面应用凭据 - 配置OAuth同意屏幕并添加测试用户 - 将凭据下载为 credentials.json

1. 安装和构建:

   bun install
   bun run build

1. 通过CLI添加Gmail帐户:

   bun src/cli.ts add your-email@gmail.com

这将打开您的浏览器以获得OAuth同意。代币保存在项目的 accounts/ 目录。

1. 配置Claude桌面版 （参见 详细步骤如下):

- 将MCP服务器条目添加到 claude_desktop_config.json - 重新启动克劳德桌面

1. 开始使用:

   Send an email to john@example.com with subject "Hello" and body "Testing Gmail MCP"

先决条件

• 包子 （最新版本）-从安装 bun.sh
• 克劳德桌面 已安装应用程序
• Gmail帐户 启用API访问
• Google 云控制台 启用Gmail API的项目

安装说明

1.谷歌云控制台设置

第一步：创建谷歌云项目

1. 首选 Google 云控制台
2. 单击页面顶部的项目下拉列表
3. 点击 新项目
4. 输入项目名称（例如“Gmail MCP服务器”），然后单击 创建
5. 确保在项目下拉列表中选择了新项目

步骤2：启用Gmail API

1. 在左侧边栏中，转到 API和服务 > 图书馆
2. 搜索 Gmail API
3. 点击它，然后点击 启用

步骤3：创建OAuth 2.0凭据

1. 在左侧边栏中，转到 API和服务 > 凭证
2. 点击 +创建凭据 在顶端
3. 选择 创建凭据 >选择 Gmail API 从“选择API”下拉列表
4. 在“您将访问哪些数据？”下，选择 用户数据 （不是“应用程序数据”）
5. 点击 下一步

步骤4：配置OAuth同意屏幕

当系统提示您配置OAuth同意屏幕时：

1. 应用程序名称：输入任何名称（例如“Gmail MCP”）
2. 用户支持电子邮件：从下拉列表中选择您的电子邮件
3. 应用程序徽标：跳过此项-留空
4. 开发人员联系电子邮件：输入您的电子邮件地址
5. 点击 保存并继续

步骤5：设置范围（可选）

1. 在“范围”屏幕上，您可以跳过此操作-只需单击 保存并继续
2. 在OAuth流期间，MCP服务器代码在运行时请求所需的作用域

步骤6：创建OAuth客户端ID

1. 在“OAuth客户端ID”屏幕上，选择 桌面应用程序 作为应用程序类型
2. 输入名称（例如“Gmail MCP桌面客户端”）或保留默认名称
3. 点击 创建

步骤7：下载凭据

1. 点击 下载 按钮下载凭据JSON文件
2. 将下载的文件重命名为 credentials.json
3. 点击 完成

步骤8：添加测试用户

由于该应用程序具有“测试”发布状态，因此只有注册的测试用户才能进行身份验证：

1. 在左侧边栏中，转到 API和服务 > OAuth 授权界面 （这将重定向到谷歌认证平台受众页面）
2. 向下滚动到 测试用户 部分
3. 点击 +添加用户
4. 输入要与MCP服务器一起使用的Gmail地址
5. 如果您计划使用多帐户功能，则可以添加多个测试用户
6. 点击 保存

2.项目设置

1. 克隆并安装:

   git clone https://github.com/Konadu-Akwasi-Akuoko/gmail-multi-mcp.git
   cd gmail-multi-mcp
   bun install

1. 构建项目:

   bun run build

1. 测试设置 （可选但推荐）：

   bun run inspect

这将打开MCP检查器，以便在连接到Claude Desktop之前测试工具。

3.克劳德桌面集成

步骤1：打开Claude Desktop的配置目录

配置目录路径包含空格(Application Support)，所以你需要引用或回避它：

macOS：

cd ~/Library/Application\ Support/Claude/
# or
cd "$HOME/Library/Application Support/Claude/"

注： 工具如 zoxide (z)不要很好地处理路径中的空格。使用标准 cd 如上所示，使用转义命令。

Windows（PowerShell）：

cd "$env:APPDATA\Claude\"

Linux：

cd ~/.config/claude/

步骤2：放置您的Google凭据

放置 credentials.json 文件在 项目根目录 （不是Claude Desktop的配置目录）：

# From wherever you downloaded it
cp ~/Downloads/credentials.json /path/to/gmail-multi-mcp/

验证它是否存在：

ls /path/to/gmail-multi-mcp/credentials.json

步骤3：编辑 claude_desktop_config.json

在编辑器中打开配置文件：

# macOS
nano ~/Library/Application\ Support/Claude/claude_desktop_config.json
# or with VS Code
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

如果文件已经有内容 （如现有 preferences)，添加 mcpServers 作为兄弟密钥-不要覆盖已有的密钥。例如，如果你的文件看起来像这样：

{
  "preferences": {
    "quickEntryDictationShortcut": "off",
    "coworkScheduledTasksEnabled": false,
    "sidebarMode": "chat"
  }
}

将其更新为：

{
  "preferences": {
    "quickEntryDictationShortcut": "off",
    "coworkScheduledTasksEnabled": false,
    "sidebarMode": "chat"
  },
  "mcpServers": {
    "gmail": {
      "command": "bun",
      "args": ["/absolute/path/to/your/gmail-multi-mcp/src/index.ts"]
    }
  }
}

如果文件为空或不存在，使用以下命令创建它：

{
  "mcpServers": {
    "gmail": {
      "command": "bun",
      "args": ["/absolute/path/to/your/gmail-multi-mcp/src/index.ts"]
    }
  }
}

重要提示： 替换 /absolute/path/to/your/gmail-multi-mcp/ 带有克隆项目的实际绝对路径。你可以通过跑步来获得这个 pwd 从项目目录中。

步骤4：验证 bun 可访问的

MCP服务器使用 bun 跑步。确保它已安装并位于您的PATH中：

which bun
# Should output something like: /Users/yourname/.bun/bin/bun

如果 bun 找不到，请从安装 bun.sh.

步骤5：重新启动克劳德桌面

完全退出 Claude Desktop（不仅仅是关闭窗口）并重新打开。在macOS上，右键单击dock图标并选择 退出，或使用 Cmd+Q.

重新启动后，Gmail MCP工具应该可以在Claude Desktop中使用。

CLI帐户管理

CLI工具与MCP服务器分开管理Gmail帐户。这是必要的，因为MCP服务器在Claude Desktop下作为后台进程运行，浏览器OAuth流无法工作。

为什么要使用单独的CLI？

当Claude Desktop生成MCP服务器时， process.cwd() 解析到Claude Desktop自己的目录，而不是项目根目录。CLI和MCP服务器都使用 import.meta.dir 解析相对于源文件的路径，以便他们始终就位置达成一致 credentials.json 和 accounts/ live（项目根）。

命令

# Add a new Gmail account (opens browser for OAuth)
bun src/cli.ts add user@gmail.com

# List all configured accounts
bun src/cli.ts list

# Get or set the default account
bun src/cli.ts default              # show current default
bun src/cli.ts default user@gmail.com  # set new default

# Re-authenticate an expired token
bun src/cli.ts reauth user@gmail.com

# Remove an account
bun src/cli.ts remove user@gmail.com

# Show the resolved data directory
bun src/cli.ts path

建成后

如果你跑过 bun run build，您还可以使用编译后的二进制文件：

bun build/cli.js list

环境变量

集 GMAIL_MCP_DATA_DIR 覆盖CLI和MCP服务器查找的位置 credentials.json 和 accounts/:

GMAIL_MCP_DATA_DIR=/custom/path bun src/cli.ts list

首次身份验证

在连接到Claude Desktop之前，通过CLI工具完成帐户设置：

1. 跑 bun src/cli.ts add your-email@gmail.com 从项目目录
2. 打开浏览器窗口以获得Google OAuth同意
3. 登录并授予请求的权限
4. 身份验证令牌存储在 accounts/ 项目根目录中的目录
5. 代币自动刷新，有效期为6个月不活动
6. MCP服务器在运行时读取这些预先存在的令牌（不需要浏览器流）

可用工具

电子邮件操作

电子邮件修改

批量操作

附件

标签管理

过滤器管理

账户管理

发展

# Development mode with hot reload
bun run dev

# Test with MCP Inspector
bun run inspect

# Build for production
bun run build

# Type-check without emitting
bun run typecheck

建筑

使用TypeScript构建并遵循MCP规范：

• 入口点: src/index.ts -MCP服务器设置和工具定义
• 命令行界面: src/cli.ts -Commander.js CLI用于基于终端的帐户管理
• Gmail客户端: src/gmail-client.ts -Gmail API包装（发送、搜索、读取、修改、删除、批量操作、附件）
• 客户经理: src/account-manager.ts -多账户凭证存储和切换
• 电子邮件实用程序: src/email-utils.ts -MIME编码、电子邮件验证、路径安全、Nodemailer集成
• 标签管理器: src/label-manager.ts -Gmail标签的CRUD操作
• 筛选器管理器: src/filter-manager.ts -Gmail过滤器CRUD和预构建模板
• 认证: src/auth.ts -OAuth 2.0证书管理
• 类型: src/types.ts -TypeScript接口和类型定义

故障排除

常见问题

“未指定帐户，也未设置默认帐户”:

• 使用CLI添加帐户： bun src/cli.ts add user@gmail.com

“身份验证失败”:

• 检查是否 credentials.json 存在于项目根目录中(bun src/cli.ts path 显示已解析的目录）
• 验证Gmail API是否已在Google云控制台中启用
• 重新验证： bun src/cli.ts reauth user@gmail.com

“令牌已过期”:

• 通过CLI重新进行身份验证： bun src/cli.ts reauth user@gmail.com

Claude Desktop未检测到MCP服务器:

• 验证中的绝对路径 claude_desktop_config.json 是正确的
• 确保 bun 在你的路径中(which bun)
• 检查一下 mcpServers 是配置中的顶级键，而不是嵌套在其中 preferences
• 确保JSON有效（没有尾随逗号，正确匹配括号）
• 完全重新启动Claude Desktop（退出+重新打开，而不仅仅是关闭窗口）
• 检查Claude Desktop日志中的MCP服务器错误

zoxide / z 找不到Claude配置目录:

• 路径包含空格(Application Support).使用 cd 使用引号或反斜杠转义：

  cd ~/Library/Application\ Support/Claude/

开发和测试

不带Claude Desktop的测试工具:

bun run inspect

热装开发模式:

bun run dev

查看服务器日志:

• 检查Claude Desktop日志中的MCP服务器输出
• 使用检查器工具进行详细的请求/响应调试

文件结构

项目目录:

gmail-multi-mcp/
├── build/                  # Compiled JavaScript (auto-generated)
├── accounts/               # Account tokens (auto-generated by CLI)
├── credentials.json        # Google OAuth credentials (you provide)
├── src/
│   ├── index.ts            # MCP server entry point and tool definitions
│   ├── cli.ts              # Commander.js CLI for account management
│   ├── gmail-client.ts     # Gmail API wrapper
│   ├── account-manager.ts  # Multi-account management
│   ├── email-utils.ts      # MIME, validation, security, Nodemailer
│   ├── label-manager.ts    # Label CRUD operations
│   ├── filter-manager.ts   # Filter CRUD and templates
│   ├── auth.ts             # OAuth 2.0 credential management
│   ├── bun.d.ts            # Bun-specific type declarations
│   └── types.ts            # TypeScript interfaces
├── package.json
└── CLAUDE.md

Claude桌面配置目录 （仅限 claude_desktop_config.json 住在这里）：

# macOS
~/Library/Application Support/Claude/claude_desktop_config.json
# Linux
~/.config/claude/claude_desktop_config.json
# Windows
%APPDATA%\Claude\claude_desktop_config.json

安全

• 使用最少的Gmail作用域
• 自动刷新本地存储的令牌
• 没有永久存储的电子邮件内容
• 所有操作均在本地执行
• 根据敏感目录（~/.ssh、~/.aws、~/.env、凭据等）验证附件路径
• 通过CR/LF剥离防止MIME头注入
• 附件下载时的路径遍历保护

局限性

• 费率限制：Gmail API有每日配额
• 令牌到期：代币在6个月不活动后过期

许可证

麻省理工学院

学分

• AlexHramovich/gmailmcp -原始Gmail MCP服务器
• 共和/Gmail MCP服务器 -附加功能灵感