AI导哈

Gmail操作协议服务器

一个全面的Gmail操作模型上下文协议（MCP）服务器，提供25种生产就绪工具和可流式传输的HTTP传输。

  • by PeterAkande
  • Python
  • 本地部署
  • 4 星标
  • 更新于
在 GitHub 查看 PeterAkande/gmail_mcp

使用说明

Gmail MCP 服务器

一个针对Gmail操作的全面模型上下文协议（MCP）服务器 25款可投入生产的工具 以及可流式传输的HTTP传输。

🚀 快速入门

先决条件

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

安装

# Clone and install dependencies
git clone <repository>
cd gmail_mcp
uv sync

开发环境设置

# Copy environment template
cp .env.example .env
# Edit .env with your configuration (see Configuration section)

# Start development server (auto-reload)
uv run python start_server.py
# OR manually with custom port
uvicorn main:app --reload --port 8002

特点/特性

完整的Gmail集成

  • 25款MCP工具 涵盖所有Gmail操作
  • OAuth 2.0 认证 使用Google令牌验证
  • 类型安全 配备全面的 Pydantic 模型

可用工具（共25个）

  • gmail_get_emails - 列出电子邮件，并应用过滤、分页和日期范围筛选
  • gmail_get_my_sent_emails - 接收带有日期过滤的电子邮件
  • gmail_get_email_by_id - 通过ID获取特定电子邮件，并应用格式选项
  • gmail_search_emails - 使用Gmail查询语法和日期范围进行高级搜索
  • gmail_get_labels - 列出所有Gmail标签及其属性
  • gmail_get_profile - 获取Gmail个人资料和账户信息
  • gmail_send_email - 发送带有附件和格式设置的新电子邮件
  • gmail_reply_to_email - 回复邮件时提供“全部回复”选项
  • gmail_mark_as_read / gmail_mark_as_unread - 管理阅读状态
  • gmail_archive_email / gmail_unarchive_email - 档案管理
  • gmail_delete_email - 删除电子邮件（移到垃圾箱）
  • gmail_add_label / gmail_remove_label - 管理电子邮件标签
  • gmail_create_label - 创建新的自定义标签
  • gmail_forward_email - 转发电子邮件并附上额外信息
  • gmail_move_to_folder - 在文件夹/标签之间移动电子邮件
  • gmail_get_threads - 列出对话线程，并应用日期过滤器
  • gmail_get_thread_by_id - 通过ID获取特定线程
  • gmail_create_draft - 创建电子邮件草稿
  • gmail_get_drafts - 列出草稿邮件，并按日期筛选
  • gmail_get_draft_by_id - 通过ID获取特定草稿
  • gmail_send_draft - 发送现有草稿
  • gmail_get_attachments - 下载电子邮件附件

配置

环境变量（.env）

# Server Configuration
SERVER_HOST=0.0.0.0                    # Server bind address
SERVER_PORT=8001                       # Server port
SERVER_URL=http://localhost:8001       # This server's URL for OAuth validation
DEBUG=false                            # Enable debug mode

# Transport Configuration
TRANSPORT_TYPE=streamble_http           # streamble_http or sse
MCP_SERVER_NAME=gmail_mcp_server       # MCP server identifier

# Logging
LOG_LEVEL=INFO                         # DEBUG, INFO, WARNING, ERROR
LOG_FORMAT=%(asctime)s - %(name)s - %(levelname)s - %(message)s

OAuth 范围（或作用域）

服务器需要以下Gmail范围权限：

  • gmail.readonly - 阅读电子邮件和标签
  • gmail.send - 发送电子邮件
  • gmail.modify - 修改电子邮件（归档、标记等）
  • gmail.compose - 创建草稿
  • gmail.labels - 管理标签

邮件格式（用于接收电子邮件时）

服务器支持5种消息格式以达到最佳性能：

紧凑型（默认）

  • 最适合于通用邮件浏览和AI处理
  • 包含头部信息 + 纯文本正文 + 元数据
  • 用例最常见的操作

最小的；最少的

  • 最适合用于列出和枚举
  • 包含仅ID、标签和片段
  • 用例高频率操作

满员/完全

  • 最适合于完整阅读电子邮件
  • 包含所有数据，包括HTML文件、附件
  • 用例显示完整电子邮件

元数据

  • 最适合用于头部分析
  • 包含所有头部信息，无正文内容
  • 用例无内容的电子邮件分析

RAW（生文件格式）

  • 最适合于电子邮件处理
  • 包含原始的RFC2822格式
  • 用例迁移，备份

日期范围筛选

大多数工具都支持灵活的日期过滤功能：

绝对日期

# YYYY-MM-DD or YYYY/MM/DD format
after_date="2024-01-01"
before_date="2024-12-31"

相对时间框架

# Days, weeks, months, years
newer_than="1d"    # Last day
older_than="6m"    # Older than 6 months

示例

# Get recent important emails
gmail_get_emails(label_ids=["IMPORTANT"], newer_than="1w", format="COMPACT")

# Search emails in date range
gmail_search_emails(query="project", after_date="2024-06-01", before_date="2024-06-30")

建筑学

MCP服务器设计

  • 交通可流式传输的HTTP（默认）或SSE
  • 认证使用带有令牌验证的Google OAuth 2.0
  • 格式基于JSON的MCP协议
  • **流媒体（传输）**大型操作的实时响应流

OAuth 流程

┌─────────────────────┐    ┌──────────────────────┐    ┌─────────────────┐
│   MCP Client        │    │   Google OAuth       │    │  Gmail MCP      │
│                     │    │   (accounts.google)  │    │  Server         │
│ 1. Request with     │────│ 2. Validates token   │────│ 3. Gmail API    │
│    Bearer token     │    │    Returns user info │    │    operations   │
│                     │    │                      │    │                 │
└─────────────────────┘    └──────────────────────┘    └─────────────────┘

API 参考文档

认证

所有终端点都需要有效的Google OAuth令牌：

Authorization: Bearer <google_oauth_token>

发展

项目设置

# Install dependencies
uv sync

# Setup environment
cp .env.example .env
# Edit .env file with your configuration

# Run tests
uv run python mail_test_main.py

# Start development server with auto-reload
uv run python start_server.py

开发命令

# Development server (auto-reload)
uv run python start_server.py

# Manual development with custom port
uvicorn main:app --reload --port 8002

# Production server
uvicorn main:app --host 0.0.0.0 --port 8001

# Run interactive tests
uv run python mail_test_main.py

测试工具

该项目包括 service_example/service_functions_test.py - 一个交互式测试套件：

  • 测试所有25项Gmail服务功能

Gmail OAuth 范围（或作用域）

服务器会自动配置这些所需的范围：

REQUIRED_SCOPES = [
    "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.compose",
    "https://www.googleapis.com/auth/gmail.labels"
]

🔐 Google OAuth 配置

  1. Google Cloud 控制台

  2. OAuth 配置

    • 添加授权来源： http://localhost:8001
    • 根据您的OAuth流程需要，添加重定向URI
    • 下载凭证（不在本服务器存储）

  3. 令牌验证

    • 此服务器使用谷歌的验证令牌 accounts.google.com - 为了快速测试获取访问令牌，请检查 service_example/get_access_token.py
    • 不存储凭证 - 每次请求验证令牌

📝 许可证

MIT 许可证 - 详见 LICENSE 文件。

相关 MCP