Gmail Server for Model Context Protocol (MCP)

Gmail 的 Model Context Protocol（MCP）服务

此 MCP 服务与 Gmail 集成，可发送、删除、读取、撰写和回复电子邮件。

注意：此服务允许 MCP 客户端读取、删除和发送电子邮件。不过，客户端会在执行这些操作前征求用户同意。

https://github.com/user-attachments/assets/5794cd16-00d2-45a2-884a-8ba0c3a90c90

组件

工具

• send-email

  • 向电子邮件地址收件人发送邮件
  • 输入：
    • recipient_id（string）：收件人的电子邮件地址
    • subject（string）：邮件主题
    • message（string）：邮件内容
  • 返回状态和 message_id

• trash-email

  • 将邮件移至垃圾箱
  • 输入：
    • email_id（string）：邮件的自动生成 ID
  • 返回成功消息

• mark-email-as-read

  • 将邮件标记为已读
  • 输入：
    • email_id（string）：邮件的自动生成 ID
  • 返回成功消息

• get-unread-emails

  • 获取未读邮件
  • 返回包含邮件 ID 的邮件列表

• read-email

  • 获取指定邮件的内容
  • 输入：
    • email_id（string）：邮件的自动生成 ID
  • 返回邮件元数据字典，并将邮件标记为已读

• open-email

  • 在浏览器中打开邮件
  • 输入：
    • email_id（string）：邮件的自动生成 ID
  • 返回成功消息，并在默认浏览器中打开指定邮件

设置

Gmail API 设置

1. 创建新的 Google Cloud 项目
2. 启用 Gmail API
3. 配置 OAuth 同意屏幕
   • 选择“外部”。不过，我们不会发布此应用。
   • 将你的个人电子邮件地址添加为“测试用户”。
4. 添加 OAuth 范围 https://www.googleapis.com/auth/gmail/modify
5. 创建 OAuth 客户端 ID，应用类型选择“桌面应用”
6. 下载包含客户端 OAuth 密钥的 JSON 文件
7. 重命名密钥文件，并将其保存到本地安全的位置。记下保存位置。
   • 启动服务时，将此文件的绝对路径作为参数 --creds-file-path 传入。

身份验证

启动服务时，系统浏览器会启动身份验证流程。 之后，令牌凭据会保存到参数 --token-path 指定的绝对文件路径中（之后也会从该路径读取）。

例如，你可以在主目录中使用点目录，并将 [your-home-folder] 替换为你的主目录。：

参数	示例
--creds-file-path	/[your-home-folder]/.google/client_creds.json
--token-path	/[your-home-folder]/.google/app_tokens.json

在桌面应用中使用

建议使用 uv。

若要将此服务作为 MCP 客户端集成到 Claude Desktop，请将以下内容添加到应用的服务配置中。默认情况下，配置文件位于 ~/Library/Application\ Support/Claude/claude_desktop_config.json。

{
  "mcpServers": {
    "gdrive": {
      "command": "uv",
      "args": [
        "--directory",
        "[absolute-path-to-git-repo]",
        "run",
        "gmail",
        "--creds-file-path",
        "[absolute-path-to-credentials-file]",
        "--token-path",
        "[absolute-path-to-access-tokens-file]"
      ]
    }
  }
}

必须设置以下参数

参数	示例
--directory	包含服务的 gmail 目录的绝对路径
--creds-file-path	Gmail API 设置中创建的凭据文件的绝对路径。
--token-path	用于存储和读取应用访问令牌与刷新令牌的绝对路径。

使用 MCP Inspector 排查问题

要测试此服务，请使用 MCP Inspector。 在 git 仓库中运行以下命令，并相应调整参数。

npx @modelcontextprotocol/inspector uv run [absolute-path-to-git-repo]/src/gmail/server.py --creds-file-path [absolute-path-to-credentials-file] --token-path [absolute-path-to-access-tokens-file]