AI导哈

Gmail API 服务器

MCP Gmail Server 是一个封装了Gmail API的服务器，提供邮件搜索、消息获取、附件管理等功能。

  • by cutsome
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 cutsome/gmail-mcp

使用说明

MCP Gmail服务器

包装Gmail API的MCP（模型上下文协议）服务器。

特性

提供以下4个工具：

  • gmail.search_messages：搜索Gmail并检索邮件ID列表
  • gmail.get_message：检索指定邮件ID的详细信息
  • gmail.get_attachments：检索指定邮件的附件列表
  • gmail.get_attachment_data：检索指定附件的附件数据（base64编码）

设置

1.安装依赖项

cd mcp-gmail-server
uv sync

2.谷歌云控制台配置

按照官方文档启用Gmail API并创建OAuth 2.0凭据：

  1. Python快速入门| Gmail -按照“设置您的环境”部分进行操作
  2. 创建访问凭据 -创建OAuth客户端ID

注： 创建OAuth客户端ID时，选择 “桌面应用程序” 作为应用程序类型。

完成这些步骤后，下载凭据JSON文件并将其重命名为 client_secret.json.

3.放置凭证文件

放置 client_secret.json 从Google Cloud控制台下载的文件 mcp-gmail-server 目录：

mcp-gmail-server/
  ├─ client_secret.json  # Place here
  └─ ...

自定义路径规范（可选）

如果你想放置 client_secret.json 在其他位置，您可以使用环境变量指定路径：

export GOOGLE_CLIENT_SECRET_PATH="/path/to/client_secret.json"

首次身份验证

首次启动时，将执行OAuth2流，并在浏览器中请求身份验证。 身份验证完成后，a token.json 将创建文件并保存刷新令牌。 后续运行将使用此功能自动进行身份验证 token.json.

用法

以MCP服务器身份启动

uv run mcp-gmail-server

服务器通过stdio处理MCP协议。

直接执行（用于测试）

uv run python -m mcp_gmail_server.main

MCP客户端配置（光标等）

将以下内容添加到您的 mcp.json （或 .cursor/mcp.json 光标）：

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-gmail-server", "mcp-gmail-server"]
    }
  }
}

替换 /path/to/mcp-gmail-server 带有此项目目录的实际路径。

使用MCP检查器进行调试

MCP Inspector允许您使用基于浏览器的UI调试MCP服务器。您可以测试工具、检查资源、测试提示等。

# Using Makefile (recommended)
make debug

# Or execute directly
npx @modelcontextprotocol/inspector uv run mcp-gmail-server

运行此命令时：

  1. MCP检查器将启动，浏览器将自动打开（默认值： http://localhost:5173)
  2. 将显示服务器连接状态、可用工具和元数据
  3. 您可以在“工具”选项卡中测试每个工具
  4. 您可以使用自定义输入执行工具并检查响应

端口定制：

CLIENT_PORT=8080 SERVER_PORT=9000 npx @modelcontextprotocol/inspector uv run mcp-gmail-server

工具详细信息

gmail.search_邮件

搜索Gmail并检索邮件ID列表。

参数：

  • query （必填）：Gmail搜索查询（例如。， "after:2025/1/1", "from:example@gmail.com")
  • max_results （可选）：最大结果数（默认值：100）

返回值：

[
  {
    "message_id": "1234567890",
    "thread_id": "0987654321"
  },
  ...
]

gmail.get_message

检索指定邮件ID的详细信息。

参数：

  • message_id （必填）：要检索的邮件的ID

返回值：

{
  "message_id": "1234567890",
  "thread_id": "0987654321",
  "subject": "Email Subject",
  "from": "sender@example.com",
  "to": "recipient@example.com",
  "received_at": "2025-01-31T10:23:45+09:00",
  "body_text": "Email body..."
}

gmail.get_附件

检索指定邮件的附件列表。

参数：

  • message_id （必填）：要从中检索附件的邮件的ID

返回值：

[
  {
    "attachment_id": "att123",
    "file_name": "receipt.pdf",
    "mime_type": "application/pdf",
    "size": 12345
  },
  ...
]

gmail.get_attachment_data

检索指定附件的附件数据（base64编码）。

参数：

  • message_id （必填）：包含附件的邮件的ID
  • attachment_id （必填）：要检索的附件的ID

返回值：

{
  "attachment_id": "att123",
  "data": "base64 encoded data",
  "size": 12345
}

故障排除

身份验证错误

  • 检查是否 client_secret.json 文件被放置在 mcp-gmail-server 目录
  • 验证以下内容 client_secret.json 正确（按原样使用从Google Cloud Console下载的文件）
  • 删除 token.json 文件并再次尝试身份验证

Gmail API错误

  • 检查Gmail API是否已启用
  • 验证OAuth 2.0凭据范围是否正确(https://www.googleapis.com/auth/gmail.readonly)

许可证

该项目根据 MIT许可证.

相关 MCP