使用说明

Gmail MCP服务器

Gmail的模型上下文协议（MCP）服务器，提供与收件箱的自然语言交互、按类别组织的每日摘要和家庭助理集成。

特性

🔍 自然语言搜索 -使用普通语言或Gmail查询语法搜索电子邮件
📊 基于类别的摘要 -自动分类：海军、儿童、金融、行动项目
📱 家庭助理集成 -支持传感器和通知的REST API
🐳 Docker支持 -使用Docker Compose轻松部署
🔒 只读的 -当前以只读方式访问您的收件箱（安全！）

快速开始

1.谷歌云设置

首选谷歌云控制台
创建新项目或选择现有项目
启用 Gmail API:
- 导航到“API和服务”→ “启用API”
- 搜索“Gmail API”并启用它
创建OAuth凭据：
- 转到“API和服务”→ “凭据”
- 点击“创建凭据”→ “OAuth客户端ID”
- 选择“Web应用程序”（或“桌面应用程序”）
- 对于Web应用程序，添加 http://localhost:8080 到 授权重定向URI
- 复制客户端ID和客户端密码

2.配置

# Clone and enter directory
cd mcp_gmail

# Copy example environment file
cp .env.example .env

# Edit .env with your credentials
# GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
# GOOGLE_CLIENT_SECRET=your-client-secret

3.初始身份验证（OAuth）

对于首次设置，您需要向Google进行身份验证：

# Run the auth setup container
docker compose --profile setup run --rm gmail-mcp-auth

这将：

打开浏览器窗口进行谷歌身份验证
请求阅读您的Gmail的权限
将OAuth令牌保存到 ./credentials/token.json

4.启动服务器

# Start the main server
docker compose up -d

# Check logs
docker compose logs -f gmail-mcp

REST API将在 http://localhost:8000

API终点

健康与状态

端点	描述
`GET /health`	带有身份验证状态的健康检查
`GET /api/stats`	收件箱统计

电子邮件数据（用于家庭助理传感器）

端点	描述
`GET /api/unread`	未读总计数
`GET /api/unread/categories`	每个类别的未读计数

摘要

端点	描述
`GET /api/summary/daily`	完整的每日摘要（JSON）
`GET /api/summary/daily/text`	每日摘要为文本
`GET /api/summary/category/{category}`	特定类别摘要

家庭助理集成

端点	描述
`POST /api/webhook/trigger`	将摘要发送到HA webhook

家庭助理配置

REST传感器

添加到您的 configuration.yaml:

sensor:
  - platform: rest
    name: Gmail Unread
    resource: http://gmail-mcp:8000/api/unread
    value_template: "{{ value_json.unread }}"
    scan_interval: 300
    json_attributes:
      - timestamp

  - platform: rest
    name: Gmail Categories
    resource: http://gmail-mcp:8000/api/unread/categories
    value_template: "{{ value_json.total }}"
    scan_interval: 300
    json_attributes:
      - navy
      - kids
      - financial
      - action_required
      - other

模板传感器（来自属性）

template:
  - sensor:
      - name: "Gmail Navy Unread"
        state: "{{ state_attr('sensor.gmail_categories', 'navy') }}"
        icon: mdi:anchor

      - name: "Gmail Kids Unread"
        state: "{{ state_attr('sensor.gmail_categories', 'kids') }}"
        icon: mdi:human-child

      - name: "Gmail Financial Unread"
        state: "{{ state_attr('sensor.gmail_categories', 'financial') }}"
        icon: mdi:currency-usd

      - name: "Gmail Action Required"
        state: "{{ state_attr('sensor.gmail_categories', 'action_required') }}"
        icon: mdi:alert-circle

自动化：每日摘要通知

automation:
  - alias: "Daily Email Summary"
    trigger:
      - platform: time
        at: "07:00:00"
    action:
      - service: rest_command.gmail_summary
      - service: notify.mobile_app
        data:
          title: "📧 Email Summary"
          message: "{{ states('sensor.gmail_summary_text') }}"

rest_command:
  gmail_summary:
    url: "http://gmail-mcp:8000/api/webhook/trigger"
    method: POST

Webhook集成

在您的 .env:

HA_WEBHOOK_URL=http://homeassistant.local:8123/api/webhook/gmail_summary
HA_LONG_LIVED_TOKEN=your-long-lived-access-token

然后创建由webhook触发的自动化：

automation:
  - alias: "Gmail Webhook Handler"
    trigger:
      - platform: webhook
        webhook_id: gmail_summary
    action:
      - service: notify.mobile_app
        data:
          title: "📧 {{ trigger.json.event_type }}"
          message: "{{ trigger.json.data.text_summary }}"

MCP服务器使用情况

MCP服务器可以通过SSE传输与Claude Desktop、Home Assistant或其他MCP客户端一起使用。

Claude桌面配置

添加到您的Claude桌面配置(claude_desktop_config.json):

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://YOUR_SERVER_IP:8001/mcp/sse", "--allow-http"]
    }
  }
}

家庭助理MCP集成

服务器为MCP连接公开SSE端点：

/mcp/sse -主MCP SSE终点
/sse -家庭助理兼容性的别名端点

可用的MCP工具

工具	说明
`gmail_search`	使用查询和可选过滤器搜索电子邮件
`gmail_get_email`	按ID获取完整的电子邮件内容
`gmail_list_unread`	使用可选类别过滤器列出未读电子邮件
`gmail_daily_summary`	生成分类的每日摘要
`gmail_category_summary`	特定类别的摘要
`gmail_inbox_stats`	当前收件箱统计信息
`gmail_list_labels`	列出所有Gmail标签
`gmail_create_label`	创建新的Gmail标签
`gmail_delete_label`	删除Gmail标签
`gmail_get_categories`	显示已配置的类别
`gmail_mark_as_read_by_ids`	将特定电子邮件标记为按ID读取
`gmail_mark_as_read_by_query`	将与查询匹配的电子邮件标记为已读
`gmail_send_email`	发送电子邮件（纯文本或HTML）
`gmail_add_labels_to_messages`	为邮件添加标签
`gmail_remove_labels_from_messages`	从邮件中删除标签

查询示例

“我有什么关于海军的未读邮件？”
“显示我的每日电子邮件摘要”
“我需要处理任何行动项目吗？”
“搜索来自学校的电子邮件”
“本周收到了哪些财务邮件？”

自定义类别

编辑 config/categories.yaml 要自定义电子邮件分类，请执行以下操作：

categories:
  navy:
    name: "Navy / Military"
    priority: high
    matchers:
      senders:
        - "@navy.mil"
        - "@mail.mil"
      subjects:
        - "orders"
        - "deployment"
      labels:
        - "Navy"

匹配器类型

发送者：发件人电子邮件/姓名部分匹配
科目：主题行部分匹配
标签：与Gmail标签完全匹配

发展

本地安装程序（不含Docker）

# Create virtual environment
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install in development mode
pip install -e ".[dev]"

# Run authentication
mcp-gmail-auth

# Run the API server
mcp-gmail-api

# Or run the MCP server (stdio)
mcp-gmail

运行测试

pytest
pytest --cov=mcp_gmail

建筑

┌─────────────────────────────────────────────────────────────┐
│                    Gmail MCP Server                         │
├─────────────────────────────────────────────────────────────┤
│  MCP Interface (stdio)          REST API (FastAPI)          │
│  └── Tools for Claude           └── Endpoints for HA        │
├─────────────────────────────────────────────────────────────┤
│                    Gmail Client                             │
│  ├── Search & List              ├── Categorization          │
│  └── OAuth2 Auth                └── Summary Generation      │
├─────────────────────────────────────────────────────────────┤
│                    Gmail API                                │
│  └── google-api-python-client                               │
└─────────────────────────────────────────────────────────────┘

路线图

[x] 只读电子邮件访问
[x] 基于类别的摘要
[x] 家庭助手REST API
[x] Docker部署
[x] 电子邮件发送
[x] Gmail标签管理（创建、删除、添加到邮件、从邮件中删除）
[x] 将电子邮件标记为已读
[x] 具有会话隔离的SSE传输
[x] Gemini兼容工具模式
[]预定摘要通知
[]IMAP回退选项

许可证

MIT许可证

故障排除

OAuth令牌已过期

# Re-run authentication
docker compose --profile setup run --rm gmail-mcp-auth

容器无法启动

检查凭据是否存在：

ls -la credentials/
# Should contain token.json

家庭助理无法连接

确保容器位于同一Docker网络上或使用主机IP：

resource: http://192.168.1.100:8000/api/unread