使用说明

该工具仍在开发中

Gmail MCP服务器

基于Docker的模型上下文协议（MCP）桥接服务器，通过OpenWebUI提供人工智能辅助的Gmail管理。该服务器使AI代理能够通过自然语言命令搜索、阅读、发送和组织电子邮件。

概述

Gmail MCP服务器由两部分组成：

MCP服务器 -与Gmail API接口的基于Python的服务器
MCP电桥 -Node.js Express服务器，用于公开OpenWebUI的HTTP API

建筑

┌─────────────────┐         ┌──────────────────┐         ┌─────────────────┐         ┌─────────────┐
│   OpenWebUI     │◄───────►│  MCP Bridge      │◄───────►│  Gmail MCP      │◄───────►│  Gmail API  │
│   Tools         │   HTTP  │  (Port 3002)     │  Docker │  Server         │  HTTPS  │             │
└─────────────────┘         └──────────────────┘         └─────────────────┘         └─────────────┘

特性

电子邮件搜索和阅读

使用Gmail搜索运营商进行高级搜索
检索包含标题和正文的完整邮件内容
查看整个对话线索
提取附件信息

电子邮件摘要

使用AI一次汇总多封电子邮件
按搜索查询筛选电子邮件，以获取目标摘要
支持未读电子邮件、日期范围和特定发件人
可配置的细节级别（有或没有全文内容）

电子邮件撰写

发送支持收件人、抄送和密件抄送的电子邮件
回复现有线程
创建和管理草稿
纯文本电子邮件支持

组织与管理

创建自定义标签
在邮件中添加/删除标签
将邮件标记为已读/未读
列出所有可用标签

附件支持

从PDF文件中提取文本
从DOCX文件中提取文本
下载纯文本附件
附件元数据提取

先决条件

码头工人 和 Docker Compose 安装
Docker权限 已配置（请参阅下面的设置）
Gmail API凭据 （访问令牌）
OpenWeb用户界面 已在运行（任何支持工具的版本）

Docker权限设置

网桥服务器需要访问Docker套接字才能与MCP服务器容器通信。您有两个选择：

选项1：将您的用户添加到docker组（推荐）

# Add your user to the docker group
sudo usermod -aG docker $USER

# Activate the changes
newgrp docker

# Verify it works
docker ps

在此之后，您可以运行docker命令而无需 sudo.

选项2：使用sudo运行

如果您不想将用户添加到docker组，请使用以下命令运行所有docker compose命令 sudo:

sudo docker-compose up -d --build

快速开始

1.克隆存储库

git clone https://github.com/taddiemason/Gmail-MCP-Server.git
cd Gmail-MCP-Server

2.获取Gmail API凭据

您需要Gmail API凭据进行身份验证。有 两种方法:

方法A：完整的OAuth（推荐-永不过期）

这是一种具有自动刷新令牌的生产就绪方法。

步骤1：创建OAuth凭据

首选谷歌云控制台-API和凭据
创建新项目或选择现有项目
点击 “+创建凭据” → “OAuth客户端ID”
如果出现提示，请配置OAuth同意屏幕：
- 用户类型：外部（除非你有谷歌工作区）
- 将您的电子邮件添加为测试用户
- 作用域：添加Gmail作用域（您将在OAuth Playground中配置）
应用程序类型： Web应用程序
姓名： Gmail MCP Server
授权重定向URI： https://developers.google.com/oauthplayground
点击创建并保存您的：
- 客户端ID （以结尾 .apps.googleusercontent.com)
- 客户端密钥

步骤2：获取刷新令牌

访问谷歌OAuth游乐场
点击 ⚙️ 齿轮图标 （右上）→ OAuth 2.0配置
检查 “使用您自己的OAuth凭据”
输入您的 客户端ID 和 客户端密钥
在左侧，选择 Gmail API v1 范围：
- https://www.googleapis.com/auth/gmail.readonly
- https://www.googleapis.com/auth/gmail.send
- https://www.googleapis.com/auth/gmail.modify
- https://www.googleapis.com/auth/gmail.labels
点击 “授权API”
使用您的Gmail帐户登录并授予权限
点击 “令牌的交换授权码”
保存您的 刷新令牌 （开始于 1//)

您现在拥有所有三个凭据：

✅ 客户端ID
✅ 客户端密钥
✅ 刷新令牌

方法B：简单访问令牌（快速启动-1小时后过期）

仅用于测试。令牌将在1小时后过期。

访问谷歌OAuth游乐场
选择 Gmail API v1 范围（与上述相同）
点击 “授权API”
代币的交换授权码
复制 访问令牌 （开始于 ya29.)

⚠️ 警告：此令牌很快过期。使用方法A进行生产。

3.配置凭据

你有 两个选项 提供您的凭据：

选项A：使用credentials.json（推荐）

创建一个 credentials.json 项目根目录中的文件：

cp credentials.json.example credentials.json

对于完整的OAuth（步骤2中的方法A）：

编辑 credentials.json 使用您的OAuth凭据：

{
  "client_id": "your_client_id.apps.googleusercontent.com",
  "client_secret": "your_client_secret",
  "refresh_token": "1//your_refresh_token"
}

对于简单访问令牌（步骤2中的方法B）：

{
  "access_token": "ya29.your_access_token"
}

重要:

此文件位于 .gitignore 不会被承诺
优先于环境变量
完整的OAuth凭据将自动刷新，永不过期

选项B：使用环境变量

编辑 .env 文件：

对于完整的OAuth：

# Recommended: Full OAuth credentials (never expire)
GOOGLE_CLIENT_ID=your_client_id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_REFRESH_TOKEN=1//your_refresh_token

# MCP Bridge Server Port (default: 3002)
MCP_PORT=3002

# Log level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

对于简单访问令牌：

# Quick start: Simple access token (expires in 1 hour)
GMAIL_ACCESS_TOKEN=ya29.your_access_token

# MCP Bridge Server Port (default: 3002)
MCP_PORT=3002

# Log level (DEBUG, INFO, WARNING, ERROR)
LOG_LEVEL=INFO

备注：如果两者都有 credentials.json 并且存在环境变量， credentials.json 优先考虑。

4.启动MCP服务器

使用安装脚本：

chmod +x setup.sh
./setup.sh

选择选项1启动服务器。

或者手动使用Docker Compose：

docker-compose up -d --build

注：如果您遇到权限错误，可能需要使用运行 sudo 或将您的用户添加到docker组（请参阅先决条件→ 上面的Docker权限设置）。

Gmail MCP Bridge将在以下网址提供： http://localhost:3002

5.向OpenWebUI添加工具

打开 OpenWebUI 在浏览器中
首选设置 → 管理面板 → 工具
点击 “+创建新工具”
复制内容 的 gmail_tools.py 来自此存储库
粘贴进入工具编辑器
配置网桥URL 在“阀门”部分：
- 如果OpenWebUI在Docker中： http://gmail-mcp-bridge:3002
- 如果OpenWebUI是本地的： http://localhost:3002
点击 “保存”
启用 Gmail工具

6.验证安装

测试运行状况端点：

curl http://localhost:3002/health

预期响应：

{
  "status": "ok",
  "service": "gmail-mcp-bridge"
}

OpenWebUI中的可用工具

在OpenWebUI中安装Gmail工具后，您可以使用以下功能：

搜索和阅读

search_emails(query, max_results, response_format) -搜索电子邮件
get_email(message_id, response_format) -获取完整的电子邮件内容
get_thread(thread_id, response_format) -获取对话线索
get_attachment_text(message_id, attachment_id, mime_type) -提取附件文本

摘要

summarize_emails(query, max_results, include_body) -汇总多封电子邮件

撰写和发送

send_email(to, subject, body, cc, bcc, thread_id) -发送电子邮件
create_draft(to, subject, body, cc) -创建草稿
list_drafts(max_results, response_format) -列出草稿
delete_draft(draft_id) -删除草稿

组织

list_labels(response_format) -列出所有标签
create_label(name, label_list_visibility, message_list_visibility) -创建标签
modify_labels(message_id, add_labels, remove_labels) -修改邮件标签
mark_read(message_id, mark_as_read) -标记为已读/未读

使用示例

在OpenWebUI中使用自然语言

安装后，您可以在OpenWebUI中询问AI助手：

Search for all unread emails from today

Summarize my emails from john@example.com this week

Send an email to jane@example.com with subject "Meeting Tomorrow" and tell her we'll meet at 2 PM

Create a draft to team@example.com about the project update

Mark message abc123 as read

Create a label called "Important" and add it to my latest email from boss@company.com

AI会自动调用相应的Gmail工具功能来完成您的请求。

配置

环境变量

变量	描述	默认值
`GMAIL_ACCESS_TOKEN`	Gmail API访问令牌（必需）	-
`MCP_PORT`	MCP网桥服务器端口	3002
`LOG_LEVEL`	日志记录级别	信息

网桥URL配置

在OpenWebUI的Gmail工具阀门设置中：

Docker网络: http://gmail-mcp-bridge:3002 （如果OpenWebUI容器位于同一网络上）
本地: http://localhost:3002 （如果OpenWebUI在Docker之外运行）
远程: http://YOUR_SERVER_IP:3002 （如果网桥位于不同的主机上）

文件结构

Gmail-MCP-Server/
├── Dockerfile              # Gmail MCP server container
├── Dockerfile.bridge       # Bridge server container
├── docker-compose.yml      # Multi-container orchestration
├── gmail_mcp.py           # Main MCP server implementation
├── bridge-server.js       # HTTP API bridge server
├── gmail_tools.py         # OpenWebUI Tool (upload to OpenWebUI)
├── requirements.txt       # Python dependencies
├── .env                   # Environment configuration
├── setup.sh              # Setup and management script
└── README.md             # This file

管理命令

使用安装脚本：

./setup.sh

选项：

启动Gmail MCP服务器
停止Gmail MCP服务器
重新启动Gmail MCP服务器
查看日志
检查状态
更新服务器
清理
退出

或者直接使用Docker Compose：

# Start servers
docker-compose up -d --build

# View logs
docker-compose logs -f

# View bridge logs only
docker-compose logs -f mcp-bridge

# View MCP server logs only
docker-compose logs -f gmail-mcp-server

# Stop servers
docker-compose down

# Restart servers
docker-compose restart

# Check status
docker-compose ps

故障排除

服务器无法启动

# Check Docker status
docker ps

# View detailed logs
docker-compose logs

# Restart servers
docker-compose restart

Docker权限错误

如果您看到以下错误：

PermissionError: [Errno 13] Permission denied
Error while fetching server API version: Connection aborted
docker: not found （在桥式集装箱内运行时）

解决方案1：将用户添加到docker组（推荐）

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in, or run:
newgrp docker

# Verify it works
docker ps

# Restart the services
docker-compose down
docker-compose up -d --build

解决方案2：使用sudo运行

sudo docker-compose down
sudo docker-compose up -d --build
sudo docker-compose logs -f

为什么会发生这种情况：

网桥容器需要执行 docker exec 与gmailmcp服务器容器通信的命令。这需要访问 /var/run/docker.sock，只能由docker组或root访问。

Gmail API身份验证错误

验证您的访问令牌是否有效且未过期
检查您是否已启用正确的Gmail API作用域
如果需要，从OAuth Playground生成新的访问令牌

端口冲突

如果端口3002已在使用中：

编辑 .env 文件： MCP_PORT=3003
编辑 docker-compose.yml：将端口映射更新为 3003:3003 和环境 PORT=3003
重新启动： docker-compose down && docker-compose up -d --build
更新OpenWebUI工具阀中的网桥URL

OpenWebUI无法连接到网桥

验证网桥是否正在运行: docker-compose ps
检查桥梁日志: docker-compose logs mcp-bridge
测试健康终点: curl http://localhost:3002/health
检查网桥URL 在OpenWebUI工具阀设置中：
- 如果两者都在同一网络上的Docker中： http://gmail-mcp-bridge:3002
- 如果OpenWebUI是本地的： http://localhost:3002
- 如果在不同的主机上： http://SERVER_IP:3002

连接Docker网络 如果需要：

docker network connect openwebui_network gmail-mcp-bridge

工具未出现在OpenWebUI中

确保您已保存 gmail_tools.py 在OpenWebUI工具中
在OpenWebUI设置中启用Gmail工具
刷新页面
检查OpenWebUI日志是否有错误

命令超时

增加OpenWebUI工具阀的超时时间（默认值：300秒）
检查Gmail API配额限制
验证网络连接

安全考虑

永不承诺 .env 文件 具有版本控制的真实凭据
将OAuth刷新令牌用于生产部署
定期轮换API证书
将Gmail API范围限制为仅需要的范围
尽可能在专用网络中运行网桥服务器
添加身份验证 桥接服务器以供生产使用
监控API使用情况并设置配额

发展

不使用Docker在本地运行

MCP服务器：

cd Gmail-MCP-Server
pip install -r requirements.txt
export GMAIL_ACCESS_TOKEN=your_token_here
python gmail_mcp.py

网桥服务器：

npm install express cors
export PORT=3002
node bridge-server.js

测试桥梁API

# Health check
curl http://localhost:3002/health

# Test search
curl -X POST http://localhost:3002/v1/tools/execute \
  -H "Content-Type: application/json" \
  -d '{
    "tool_name": "gmail_search_messages",
    "arguments": {
      "query": "is:unread",
      "max_results": 5
    }
  }'

API 参考

桥梁端点

健康检查

GET /health
Response: {"status": "ok", "service": "gmail-mcp-bridge"}

执行工具

POST /v1/tools/execute
Content-Type: application/json

Body:
{
  "tool_name": "gmail_search_messages",
  "arguments": {
    "query": "is:unread",
    "max_results": 10
  }
}

依赖项

Python包 （gmailmcp服务器）：

mcp -模型上下文协议框架
fastmcp -快速MCP服务器实施
httpx -异步HTTP客户端
pydantic -数据验证
PyPDF2 -PDF文本提取（可选）
python-docx -DOCX文本提取（可选）

Node.js包 （mcp桥）：

express -Web服务器框架
cors -CORS中间件

贡献

欢迎投稿！拜托：

分叉存储库
创建要素分支
进行更改
彻底测试
提交拉取请求

许可证

此项目根据MIT许可证获得许可-有关详细信息，请参阅许可证文件。

致谢

内置模型上下文协议（MCP）
专为 OpenWeb用户界面
使用Gmail API进行电子邮件操作
灵感来自Kali Pentest MCP桥架构

支持

对于问题、疑问或贡献：

在GitHub上打开一个问题
检查现有文档
查看Gmail API文档

更新日志

v2.0.0版本

添加了MCP网桥服务器架构
创建了OpenWebUI工具，便于集成
添加了所有13个Gmail管理工具
电子邮件摘要功能
全面的文件

v1.0.0

与Gmail基本集成的初始版本