MCP 服务器

Enhanced Gmail MCP Server

一个模型上下文协议服务器，使像 Claude 这样的人工智能助手能够通过自然语言与 Gmail 互动，提供全面的电子邮件管理功能，包括发送、阅读、组织、搜索以及管理草稿和标签。

README

增强型 Gmail MCP 服务器

一个功能强大且特性丰富的 Model Context Protocol (MCP) 服务器，用于 Gmail 集成，使用 Python 编写。该服务器使 AI 助手（如 Claude）能够通过自然语言与 Gmail 交互，提供全面的电子邮件管理功能。

🌟 主要特性

📧 完整的电子邮件管理

发送具有可自定义主题、内容和收件人的电子邮件
读取和检索包含完整元数据的电子邮件内容
将电子邮件移动到垃圾箱并进行确认
将电子邮件标记为已读/未读
直接在浏览器中打开电子邮件

📝 草稿管理

创建草稿电子邮件以供稍后查看
列出所有草稿电子邮件
编辑现有草稿

🏷️ 高级标签管理

列出所有可用标签
创建自定义标签
将标签应用于电子邮件/从电子邮件中删除标签
重命名现有标签
删除未使用的标签
按标签搜索电子邮件

📁 文件夹组织

创建新文件夹（实现为 Gmail 标签）
在文件夹之间移动电子邮件
列出所有可用文件夹

🔍 强大的搜索和过滤

使用 Gmail 的高级查询语法搜索电子邮件
创建、管理和删除电子邮件过滤器
按发件人、收件人、主题、内容等进行过滤
使用灵活的参数自定义搜索结果

🗄️ 存档管理

存档电子邮件（从收件箱中删除但不删除）
批量存档符合搜索条件的多个电子邮件
列出所有已存档的电子邮件
将已存档的电子邮件恢复到收件箱

🚀 快速开始

前提条件

Python 3.8+
启用了 Gmail API 的 Google Cloud 项目
OAuth 2.0 凭据

安装

# 克隆存储库
git clone https://github.com/theposch/gmail-mcp.git
cd gmail-mcp

# 设置虚拟环境
python -m venv .venv
source .venv/bin/activate  # 在 Windows 上: .venv\Scripts\activate

# 安装包
pip install -e .

Google Cloud 设置

创建一个新的 Google Cloud 项目
启用 Gmail API
配置 OAuth 同意屏幕:
- 选择“外部”用户类型
- 将您的电子邮件添加为测试用户
- 添加范围：https://www.googleapis.com/auth/gmail/modify
创建 OAuth 2.0 凭据:
- 选择“桌面应用”作为应用程序类型
- 下载 JSON 凭据文件

配置

安全地存储您的凭据，并在运行服务器时指定其位置：

# 凭据的示例目录结构
mkdir -p ~/.gmail-mcp
# 移动您下载的凭据文件
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

🔧 用法

与 Claude Desktop 一起运行

将以下内容添加到您的 Claude Desktop 配置文件（通常位于 ~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/absolute/path/to/credentials.json",
        "--token-path",
        "/absolute/path/to/tokens.json"
      ]
    }
  }
}

使用 MCP Inspector 进行测试

对于测试和调试，请使用 MCP Inspector：

npx @modelcontextprotocol/inspector uv run /path/to/gmail-mcp/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json

🔐 安全注意事项

永远不要将凭据或令牌文件提交到版本控制
将凭据存储在具有适当权限的安全位置
服务器将在执行敏感操作之前请求用户确认
定期查看 Google Cloud Console 以查找异常活动
考虑使用环境变量来存储敏感路径

🛠️ 架构

此实现具有全面的单文件架构，可通过 Google API 客户端库处理所有 Gmail 操作。主要组件包括：

具有自动令牌刷新的 OAuth2 身份验证
全面的错误处理和日志记录
具有清晰输入模式的结构化工具定义
高效的电子邮件解析和格式化

📚 示例提示

在连接 Gmail MCP 服务器后，尝试使用 Claude 的这些提示：

"Show me my unread emails" (显示我的未读邮件)
"Search for emails from example@domain.com with attachments" (搜索来自 example@domain.com 且带有附件的邮件)
"Create a new label called 'Important Projects'" (创建一个名为“重要项目”的新标签)
"Draft an email to john@example.com about the upcoming meeting" (起草一封关于即将举行的会议的电子邮件给 john@example.com)
"Archive all emails from newsletter@example.com" (存档来自 newsletter@example.com 的所有电子邮件)
"Create a filter to automatically label emails from my team" (创建一个过滤器以自动标记来自我团队的电子邮件)