AI导哈

Gmail模型上下文协议服务器

一个全面的Gmail模型上下文协议（MCP）服务器，提供17种工具，包括交互式CLI设置向导、基于浏览器的Web UI向导和完整的Docker支持。

  • by enoch-sit
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 enoch-sit/gmail-mcp-server

使用说明

Gmail MCP服务器

全面 模型上下文协议（MCP）服务器 对于Gmail，它有17个工具、一个交互式CLI设置向导、一个基于浏览器的Web UI向导和完整的Docker支持。

特性

工具 说明
list_emails 使用可选的查询过滤器列出收件箱或任何标签中的电子邮件
read_email 阅读完整的电子邮件内容（标题+解码正文）
search_emails 使用Gmail查询语法进行搜索
list_attachments_with_safety 列出带有基于策略的安全检查的邮件附件
validate_attachment 根据本地文件安全策略验证一个附件
download_attachment_safe 只有通过安全策略检查的附件才能下载
redact_text_local 通过本地隐私管道修改敏感文本
read_email_with_privacy 阅读一封主题/摘录/正文经过隐私编辑的电子邮件
send_email 发送纯文本或HTML电子邮件
create_draft 创建电子邮件草稿而不发送
reply_to_email 回复电子邮件线程（保留线程头）
delete_email 回收或永久删除电子邮件
mark_as_read 将电子邮件标记为已读
mark_as_unread 将电子邮件标记为未读
set_labels 添加/删除电子邮件上的标签
get_labels 列出所有带有邮件计数的Gmail标签
get_profile 获取经过身份验证的用户配置文件信息

附件安全策略默认值在中定义 src/config/attachment-policy.json. 隐私政策默认值在中定义 src/config/privacy-policy.json.

可选的本地隐私堆栈（vLLM+隐私编排器）可以使用Docker配置文件启动：

docker compose --profile privacy up --build

隐私配置文件还支持可选的持久服务：

  • 瑞迪斯 (redis:6379)--用于会话感知PII重新识别的令牌存储（未来功能）
  • SQLite (audit.db)--所有PII检测和合规性编辑的审计日志

看 建筑.md 了解数据库设计细节。

先决条件

  • Node.js 20+ （用于本地设置）
  • 码头工人 （适用于集装箱设置）
  • A. 谷歌云项目 启用Gmail API和OAuth2客户端ID（桌面应用程序类型）

谷歌云设置（一次性）

  1. 首选 https://console.cloud.google.com/
  2. 创建或选择项目
  3. API和服务→ 图书馆 → 搜索“Gmail API”→ 启用
  4. API和服务→ 凭证→ 创建凭据→ OAuth 2.0客户端ID
    • 应用程序类型： 桌面应用
    • 添加授权重定向URI：
      • http://localhost:3333/oauth/callback ← CLI向导
      • http://localhost:3000/oauth/callback ← Web UI向导
  5. 注意你的 客户端ID 和 客户端密钥 （或下载 credentials.json)

快速开始

选项A-CLI向导（推荐给开发人员）

# 1. Install dependencies and build
npm install
npm run build

# 2. Run the interactive CLI setup wizard
npm run setup:cli

# 3. Start the MCP server
npm start

CLI向导将：

  • 指导您完成凭证输入（文件/粘贴JSON/手动输入）
  • 允许您选择Gmail权限范围
  • 打开浏览器进行谷歌登录
  • 自动捕获OAuth回调并保存令牌
  • 验证连接并打印电子邮件+下一步

选项B——Web UI向导（基于浏览器）

# 1. Install dependencies and build
npm install
npm run build

# 2. Start the setup wizard UI
npm run setup:ui

# 3. Open http://localhost:3000 in your browser
#    Complete the 4-step wizard, then start the server:
npm start

Web UI提供了一个有指导的4步流程：

  1. 输入OAuth2凭据
  2. 选择权限范围
  3. 点击 授权Gmail访问 → 完成Google登录流程
  4. 包含连接统计信息和后续步骤的成功页面

选项C——手动 .env （CI/Docker生产）

# Copy and fill in the template
cp .env.example .env
# Edit .env: set GMAIL_CLIENT_ID, GMAIL_CLIENT_SECRET, GMAIL_REFRESH_TOKEN

npm install
npm run build
npm start

码头工人

塑造形象

docker build -t gmail-mcp-server .

运行MCP服务器（使用env变量）

# Copy .env.example → .env and fill in credentials
cp .env.example .env

docker compose up

或者在线传递凭据：

docker run -i \
  -e GMAIL_CLIENT_ID=your-client-id \
  -e GMAIL_CLIENT_SECRET=your-secret \
  -e GMAIL_REFRESH_TOKEN=your-refresh-token \
  gmail-mcp-server

通过Docker运行Web UI安装向导

docker compose -f docker-compose.setup.yml up

然后打开 http://localhost:3000 --凭据将写回 ./credentials/ 通过卷装载在主机上。

装载凭据文件而不是环境变量

docker run -i \
  -v ./credentials:/app/credentials:ro \
  gmail-mcp-server

环境变量

变量 必填 描述
GMAIL_CLIENT_ID 是* 谷歌OAuth2客户端ID
GMAIL_CLIENT_SECRET 是* 谷歌OAuth2客户端密码
GMAIL_REFRESH_TOKEN 是* 长期刷新令牌（来自安装向导）
GMAIL_REDIRECT_URI 否 覆盖重定向URI（默认值： http://localhost:3000/oauth/callback)
PORT 否 Web UI设置服务器端口（默认值： 3000)

*使用env变量时需要。或者，使用 credentials/credentials.json + credentials/token.json （由安装向导编写）。

添加到MCP客户端（例如Claude Desktop）

编辑您的MCP客户端配置：

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

或者使用Docker：

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "GMAIL_CLIENT_ID=...",
        "-e", "GMAIL_CLIENT_SECRET=...",
        "-e", "GMAIL_REFRESH_TOKEN=...",
        "gmail-mcp-server"
      ]
    }
  }
}

项目结构

├── src/
│   ├── index.ts                  # MCP server entry point
│   ├── gmail/
│   │   ├── auth.ts               # OAuth2 credential + token management
│   │   └── client.ts             # Gmail API client factory (singleton)
│   ├── tools/
│   │   ├── emails.ts             # list_emails, read_email, search_emails
│   │   ├── compose.ts            # send_email, create_draft, reply_to_email
│   │   ├── manage.ts             # delete_email, mark_as_read/unread, set_labels
│   │   └── meta.ts               # get_labels, get_profile
│   └── setup/
│       ├── oauth.ts              # Shared OAuth2 URL generation + token exchange
│       ├── cli.ts                # Interactive CLI setup wizard
│       └── ui-server.ts          # Express Web UI setup server
├── public/
│   └── setup/
│       └── index.html            # 4-step Web UI wizard (vanilla HTML/CSS/JS)
├── credentials/                  # Runtime secrets — gitignored
│   └── .gitkeep
├── Dockerfile                    # Multi-stage build (build + runtime)
├── docker-compose.yml            # MCP server runtime
├── docker-compose.setup.yml      # Web UI setup wizard runtime
├── .env.example                  # Environment variable template
└── tsconfig.json

安全说明

  • credentials/ 被忽视了-- 从不 承诺 credentials.json 或 token.json
  • 凭据是 未烘焙到Docker映像中 --始终通过env变量或卷挂载注入
  • Web UI服务器和CLI回调服务器绑定到 127.0.0.1 仅限（不可公开访问）
  • 运行时Docker容器以非root用户身份运行(mcp)

故障排除

问题 解决方案
No Gmail credentials found 快跑 npm run setup:cli 或 npm run setup:ui
No Gmail token found 重新运行安装向导以重新授权
invalid_client 来自谷歌 检查客户端ID和密码是否正确
redirect_uri_mismatch 确保在Google Cloud Console中添加的重定向URI与向导中显示的完全一致
Port 3333 in use 使用端口3333终止进程，或临时更改 CLI_PORT 在 src/setup/cli.ts
令牌已过期/ invalid_grant 重新运行安装向导以获取新的刷新令牌
Docker： credentials not found 山 ./credentials:/app/credentials 或设置环境变量

相关 MCP