AI导哈

Gmail邮件管理服务器

一个基于Rust构建的Gmail邮件管理服务器，提供搜索、读取和管理Gmail邮件的功能，可作为持久HTTP服务器运行。

  • by mstump
  • Rust
  • 本地部署
  • 更新于
在 GitHub 查看 mstump/gmail-mcp-server

使用说明

Gmail MCP服务器

一种模型上下文协议（MCP）服务器，提供搜索、阅读和管理Gmail电子邮件的工具。使用Rust构建，旨在作为持久HTTP服务器运行。

特性

  • 搜索Gmail帖子 -带有查询字符串的完整Gmail搜索功能
  • 创建和管理草稿 -使用线程感知创建电子邮件草稿
  • 提取附件文本 -从PDF、DOCX和TXT附件中安全提取文本
  • 获取电子邮件正文 -检索线程的完整电子邮件内容
  • 下载附件 -将附件下载到本地文件系统
  • 转发电子邮件 -转发包含原始内容的电子邮件
  • 发送草稿 -发送现有的电子邮件草稿

先决条件

  • 锈1.91或更高版本
  • 启用Gmail API的谷歌云项目
  • OAuth 2.0凭据（客户端ID和客户端密钥）

设置

1.谷歌云项目设置

创建谷歌云项目

  1. 首选 谷歌云控制台
  2. 点击顶部的“选择项目”下拉菜单
  3. 点击“新建项目”
  4. 输入项目名称（例如“Gmail MCP服务器”）
  5. 点击“创建”

启用Gmail API

  1. 在您的项目中，转到“API和服务”→ “图书馆”
  2. 搜索“Gmail API”
  3. 点击“Gmail API”并点击“启用”

创建OAuth 2.0凭据

  1. 转到“API和服务”→ “凭据”
  2. 点击“创建凭据”→ “OAuth客户端ID”
  3. 如果出现提示，请配置OAuth同意屏幕：
    • 选择“外部”用户类型
    • 填写必填字段（应用程序名称、用户支持电子邮件、开发人员电子邮件）
    • 将您的电子邮件添加到“测试用户”部分
    • 保存并继续执行所有步骤
  4. 返回凭据，单击“创建凭据”→ “OAuth客户端ID”
  5. 选择“桌面应用程序”作为应用程序类型
  6. 输入名称（例如，“Gmail MCP客户端”）
  7. 点击“创建”
  8. 重要：复制 客户端ID 和 客户端密钥 从确认对话框

OAuth范围

服务器请求以下OAuth作用域：

  • https://www.googleapis.com/auth/gmail.readonly -阅读Gmail邮件
  • https://www.googleapis.com/auth/gmail.compose -创建并发送草稿

建筑

使用Make（推荐）

该项目包括一个Makefile，其中包含方便的构建目标：

# Build the release binary (default)
make

# Or explicitly
make build

# Build debug binary
make build-dev

# Run tests
make test

# Build Docker image
make docker

# Clean build artifacts
make clean

# Run all: clean, deps, test, build, docker
make all

手动构建

# Get dependencies
cargo fetch

# Build release binary
cargo build --release

# Build debug binary
cargo build

# Run tests
cargo test

二进制文件将位于 target/release/gmail-mcp-server （或 target/debug/gmail-mcp-server 用于调试版本）。

配置

服务器可以通过命令行标志和环境变量进行配置。

命令行标志

跑 gmail-mcp-server --help 查看命令和标志的完整列表。

  • --gmail-client-id：您的Google OAuth客户端ID
  • --gmail-client-secret：您的Google OAuth客户端密码
  • --app-data-dir：用于存储应用程序数据（例如令牌）的自定义目录

HTTP服务器标志(http 命令）：

  • --port：HTTP服务器端口（默认值：8080）
  • --oauth-redirect-url：自定义OAuth重定向URL
  • --metrics-route：度量端点路径
  • --http-stream-route：HTTP流端点路径
  • --sse-prefix：SSE路由器前缀路径
  • --login-route：登录端点路径
  • --callback-route：OAuth回调端点路径
  • --health-route：健康检查终结点路径
  • --root-route：根端点路径

环境变量

服务器还支持与CLI标志相对应的环境变量。

  • GMAIL_CLIENT_ID
  • GMAIL_CLIENT_SECRET
  • APP_DATA_DIR
  • PORT
  • OAUTH_REDIRECT_URL
  • METRICS_ROUTE
  • HTTP_STREAM_ROUTE
  • SSE_PREFIX
  • LOGIN_ROUTE
  • CALLBACK_ROUTE
  • HEALTH_ROUTE
  • ROOT_ROUTE

使用a .env 文件

创建一个 .env 项目根目录中的文件：

# Required
GMAIL_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=your_client_secret_here

# Optional
PORT=8080

服务器自动从 .env 文件（如果存在）。

文件存储位置

服务器将身份验证令牌存储在以下位置：

  • 视窗: %APPDATA%\\gmail-mcp-server-data\\
  • macOS/Linux: ~/.gmail-mcp-server-data/

令牌文件存储为 token.json 在这个目录中。

运行服务器

服务器现在通过CLI命令进行管理。

http 命令

运行HTTP服务器。所有标志都是可选的。

# Run with default settings
gmail-mcp-server http

# Run with custom port
gmail-mcp-server http --port 3000

# Run with custom client ID and secret
gmail-mcp-server --gmail-client-id "YOUR_ID" --gmail-client-secret "YOUR_SECRET" http

tools 命令

直接从命令行访问MCP工具。

注： 全部 tools 子命令需要 --gmail-client-id 和 --gmail-client-secret 可以设置为标志或环境变量。

search-threads

搜索Gmail帖子。

gmail-mcp-server tools search-threads "from:test@example.com" --max-results 5

create-draft

创建新草稿。

gmail-mcp-server tools create-draft "recipient@example.com" "Subject" "Body" --thread-id "thread123"

extract-attachment

从附件中提取文本。

gmail-mcp-server tools extract-attachment "message123" "report.pdf"

fetch-email-bodies

获取一个或多个线程ID的电子邮件正文。

gmail-mcp-server tools fetch-email-bodies "thread123" "thread456"

download-attachment

下载附件。

gmail-mcp-server tools download-attachment "message123" "invoice.pdf" --download-dir "/tmp/downloads"

forward-email

转发电子邮件。

gmail-mcp-server tools forward-email "message123" "forward-to@example.com" "Fwd: Subject" "Please see this"

send-draft

发送草稿。

gmail-mcp-server tools send-draft "draft123"

服务器端点

服务器公开以下HTTP端点：

  • 根 (GET /)-带有端点文档的服务器信息页面
  • 健康检查 (GET /health)-健康检查端点（返回 200 OK)
  • 登录 (GET /login)-OAuth身份验证启动（重定向到Google OAuth）
  • 回调 (GET /callback)OAuth回调处理程序（处理OAuth响应）
  • 指标 (GET /metrics)-Prometheus指标端点（返回Prometheus格式的指标）
  • HTTP流 (POST /stream)-通过HTTP流传输的MCP协议端点
  • 上海证券交易所 (GET /sse/sse)-MCP协议的服务器发送事件端点
  • SSE职位 (POST /sse/message)-基于SSE的MCP协议的POST端点

注： 所有路线路径都可以通过环境变量进行自定义（请参见 配置 部分）。

Docker部署

构建Docker镜像

make docker

# Or manually
docker build -t gmail-mcp-server:latest .

运行容器

docker run -d \
  --name gmail-mcp-server \
  -p 8080:8080 \
  -e GMAIL_CLIENT_ID=your_client_id_here.apps.googleusercontent.com \
  -e GMAIL_CLIENT_SECRET=your_client_secret_here \
  gmail-mcp-server:latest

使用环境文件

创建一个 .env 文件：

GMAIL_CLIENT_ID=your_client_id_here.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=your_client_secret_here
PORT=8080

然后运行：

docker run -d \
  --name gmail-mcp-server \
  -p 8080:8080 \
  --env-file .env \
  gmail-mcp-server:latest

持久令牌存储

要在容器重启时持久化OAuth令牌，请挂载一个卷：

docker run -d \
  --name gmail-mcp-server \
  -p 8080:8080 \
  -v $(pwd)/.gmail-mcp-server-data:/root/.gmail-mcp-server-data \
  -e GMAIL_CLIENT_ID=your_client_id_here.apps.googleusercontent.com \
  -e GMAIL_CLIENT_SECRET=your_client_secret_here \
  gmail-mcp-server:latest

自定义端口

docker run -d \
  --name gmail-mcp-server \
  -p 3000:3000 \
  -e PORT=3000 \
  -e GMAIL_CLIENT_ID=your_client_id_here.apps.googleusercontent.com \
  -e GMAIL_CLIENT_SECRET=your_client_secret_here \
  gmail-mcp-server:latest

容器管理

# View logs
docker logs gmail-mcp-server

# Stop the container
docker stop gmail-mcp-server

# Start the container
docker start gmail-mcp-server

# Remove the container
docker rm gmail-mcp-server

MCP客户端配置

光标

  1. 按 Ctrl+Shift+P （Windows/Linux）或 Cmd+Shift+P （Mac）
  2. 键入“MCP”并选择“MCP：添加新服务器”
  3. 编辑配置文件

添加以下配置：

{
  "mcpServers": {
    "gmail": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

克劳德桌面

  1. 转到“文件”>“设置”>“开发人员”>“编辑配置”
  2. 编辑配置文件

添加以下配置：

{
  "mcpServers": {
    "gmail": {
      "url": "http://localhost:8080/mcp",
      "transport": "http"
    }
  }
}

手动配置

您可以直接编辑这些配置文件：

  • 光标: ~/.cursor/mcp.json （macOS/Linux）或 %APPDATA%\Cursor\mcp.json （Windows）
  • 克劳德桌面: %APPDATA%\Claude\claude_desktop_config.json （Windows）或 ~/Library/Application Support/Claude/claude_desktop_config.json （macOS）

发展

运行测试

# Run all tests
make test

# Or with cargo
cargo test

# Run with verbose output
cargo test --verbose

日志记录

服务器使用 tracing 用于伐木的板条箱。设置 RUST_LOG 用于控制日志级别的环境变量：

# Debug logging
RUST_LOG=debug ./gmail-mcp-server

# Info logging (default)
RUST_LOG=info ./gmail-mcp-server

# Error logging only
RUST_LOG=error ./gmail-mcp-server

故障排除

身份验证问题

如果遇到身份验证错误：

  1. 删除令牌文件： rm ~/.gmail-mcp-server-data/token.json （或Windows上的等效程序）
  2. 重新启动服务器
  3. 再次访问登录URL： http://localhost:8080/login

端口已在使用中

如果端口8080已在使用中：

# Use a different port
PORT=3000 ./gmail-mcp-server

OAuth重定向URL不匹配

确保Google Cloud Console中的OAuth重定向URL匹配：

  • http://localhost:8080/callback （默认）
  • 或您配置的 OAUTH_REDIRECT_URL

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

相关 MCP