Gmail MCP 服务器

一个提供 Gmail 只读访问权限的模型上下文协议 (MCP) 服务器。允许 Claude Code 安全地搜索、阅读和分析您的 Gmail 收件箱。

功能

• search_emails - 使用 Gmail 查询语法进行搜索

• list_unread - 列出未读邮件

• get_message - 获取包含附件元数据的完整消息内容

• get_thread - 获取会话线程中的所有消息

• draft_reply - 准备回复草稿内容（不会发送）

Related MCP server: Gmail MCP Server

先决条件

• Node.js 18+

• 已启用 Gmail API 的 Google Cloud 项目

• OAuth 2.0 桌面应用凭据

Google Cloud 设置

1. 创建 Google Cloud 项目

1. 前往 Google Cloud 控制台

2. 点击“选择项目” → “新建项目”

3. 为您的项目命名（例如：“Gmail MCP Server”）

4. 点击“创建”

2. 启用 Gmail API

1. 在您的项目中，前往“API 和服务” → “库”

2. 搜索“Gmail API”

3. 点击它并按“启用”

3. 配置 OAuth 同意屏幕

1. 前往“API 和服务” → “OAuth 同意屏幕”

2. 选择“外部”（如果使用 Google Workspace，则选择“内部”）

3. 填写必填字段：

   • 应用名称：“Gmail MCP Server”

   • 用户支持电子邮件：您的电子邮件

   • 开发者联系信息：您的电子邮件

4. 点击“保存并继续”

5. 添加范围：

   • https://www.googleapis.com/auth/gmail.readonly

   • https://www.googleapis.com/auth/gmail.compose

6. 将您的电子邮件添加为测试用户（如果是“外部”类型）

7. 完成设置

4. 创建 OAuth 凭据

1. 前往“API 和服务” → “凭据”

2. 点击“创建凭据” → “OAuth 客户端 ID”

3. 选择“桌面应用”作为应用类型

4. 命名（例如：“Gmail MCP Desktop”）

5. 点击“创建”

6. 下载或复制客户端 ID 和客户端密钥

安装

# Clone or navigate to the project
cd gmail-mcp

# Install dependencies
npm install

# Build the project
npm run build

配置

1. 复制示例环境变量文件：

cp .env.example .env

2. 使用您的 OAuth 凭据编辑 .env 文件：

CLIENT_ID=your-client-id.apps.googleusercontent.com
CLIENT_SECRET=your-client-secret

首次运行（授权）

首次运行服务器时，它将：

1. 打开浏览器进行 Google 授权

2. 要求您登录并授予权限

3. 将令牌本地保存到 token.json 中

后续运行将自动重用保存的令牌。

与 Claude Code 配合使用

添加 MCP 服务器

claude mcp add gmail node ./dist/index.js

或者手动添加到您的 Claude Code 配置中：

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["./dist/index.js"],
      "cwd": "/path/to/gmail-mcp"
    }
  }
}

可用工具

search_emails

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

Query examples:
- "from:user@example.com"
- "subject:meeting"
- "is:unread"
- "after:2024/01/01 before:2024/12/31"
- "has:attachment filename:pdf"
- "in:inbox -category:promotions"

list_unread

列出未读邮件（is:unread 搜索的快捷方式）。

get_message

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

get_thread

通过会话 ID 获取会话线程中的所有消息。

draft_reply

准备对会话的回复草稿。提供撰写回复的上下文，但不会发送任何邮件。

开发

# Run in development mode (with hot reload)
npm run dev

# Type check
npm run typecheck

# Build for production
npm run build

# Run production build
npm start

安全说明

• OAuth 令牌存储在本地的 token.json 中

• 切勿将 .env 或 token.json 提交到版本控制系统

• 服务器仅请求只读和撰写权限

• 不会发送任何邮件 - draft_reply 仅准备内容

• 不会记录邮件内容

故障排除

“Missing CLIENT_ID or CLIENT_SECRET”

确保您的 .env 文件存在且包含有效的凭据。

“Authorization timeout”

OAuth 流程有 5 分钟的超时限制。请重启服务器并及时完成授权。

“Token refresh failed”

删除 token.json 并重新授权。

“Access blocked: This app's request is invalid”

确保您的 OAuth 同意屏幕配置正确，并且您的电子邮件已添加为测试用户。