使用说明

📧 Gmail MCP服务器

双模Gmail集成：直接CLI操作+用于AI助手的MCP服务器

概述

Gmail MCP服务器是一个多功能的。NET全球工具，将您的Gmail帐户与人类用户和人工智能助手连接起来。它提供了两种不同的操作模式：

命令行接口命令模式 -直接的命令行界面，用于使用熟悉的终端命令搜索消息、阅读电子邮件和下载附件。

MCP模式 -模型上下文协议服务器，使人工智能助手（如克劳德）能够通过标准化协议与您的Gmail帐户进行交互。

它解决了什么问题

AI电子邮件集成：让AI助手安全、受控地访问您的Gmail，而无需共享密码
终端电子邮件访问：从命令行快速搜索和阅读电子邮件，以进行脚本编写和自动化
OAuth2安全：基于浏览器的身份验证流，带有本地凭据存储
交叉平台的：适用于Windows、macOS和Linux。NET运行时

✨ 特性

🔄 双模架构 -在CLI和MCP服务器模式之间无缝切换
🔐 OAuth2自动身份验证 -基于浏览器的安全身份验证，具有自动令牌刷新功能
📧 Gmail操作 -使用Gmail查询语法搜索邮件，阅读完整的电子邮件内容，下载附件
🤖 MCP集成 -人工智能助手的标准化协议（Claude Desktop、Cline等）
📦 简易安装 -可用。NET全局工具通过NuGet
🔍 高级搜索 -完整的Gmail查询语法支持（发件人：、主题：、是：未读等）
💻 脚本友好 -用于自动化和集成的JSON输出模式
🌐 跨平台 -到处跑。支持NET 8.0或10.0

🚀 快速开始

# Install the global tool
dotnet tool install -g GmailMcp

# Authenticate with your Gmail account
dotnet-gmail auth

# Search for messages (CLI mode)
dotnet-gmail search "from:example@gmail.com"

# Read a specific message
dotnet-gmail read <message-id>

# Start MCP server for AI assistants
dotnet-gmail mcp

📦 安装

先决条件

.NET 8.0或10.0 SDK - 点击此处下载
谷歌云控制台帐户 -OAuth2凭据需要
Gmail帐户 -您要访问的帐户

步骤1:谷歌云控制台设置

首选谷歌云控制台
创建新项目或选择现有项目
启用 Gmail API 为您的项目
导航到凭证 > 创建凭据 > OAuth 2.0客户端ID
选择 桌面应用程序 作为应用程序类型
下载凭据JSON文件
将其重命名为 gcp-oauth.keys.json
把它放进去 ~/.gmail-mcp/ （如果需要，创建目录）

文件位置：

窗户： %USERPROFILE%\.gmail-mcp\gcp-oauth.keys.json
macOS/Linux： ~/.gmail-mcp/gcp-oauth.keys.json

步骤2：安装工具

dotnet tool install -g GmailMcp

步骤3：身份验证

dotnet-gmail auth

这将：

打开默认浏览器
提示您登录谷歌
请求访问您的Gmail的权限
将OAuth2令牌保存在本地 ~/.gmail-mcp/token.json

🔧 用法

命令行接口命令模式

认证

# Authenticate and store credentials
dotnet-gmail auth

搜索邮件

# Basic search
dotnet-gmail search "from:john@example.com"

# Search with subject
dotnet-gmail search "subject:invoice"

# Complex query
dotnet-gmail search "from:support@company.com is:unread after:2024/01/01"

# Limit results (default: 10)
dotnet-gmail search "from:boss@company.com" --max-results 5

# JSON output for scripting
dotnet-gmail search "is:unread" --robot

常见搜索运算符：

from:user@example.com -来自特定发件人的电子邮件
to:user@example.com -发送给特定收件人的电子邮件
subject:keyword -主题包含关键字
is:unread -仅限未读邮件
has:attachment -带有附件的邮件
after:2024/01/01 -日期后的消息
before:2024/12/31 -日期前的消息

阅读消息

# Read message by ID (get ID from search results)
dotnet-gmail read 18d4f2a3b5c6e7f8

# JSON output
dotnet-gmail read 18d4f2a3b5c6e7f8 --robot

下载附件

# Download to current directory
dotnet-gmail download <message-id> <attachment-id>

# Download to specific directory
dotnet-gmail download <message-id> <attachment-id> --output ./downloads

# Custom filename
dotnet-gmail download <message-id> <attachment-id> --filename report.pdf

MCP模式

快速MCP设置

将以下内容添加到您的Claude Desktop配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gmail": {
      "command": "dotnet-gmail",
      "args": ["mcp"]
    }
  }
}

更改后重新启动Claude Desktop。

有关详细的MCP配置说明、故障排除和高级设置选项，请参阅 MCP配置指南.

可用的MCP工具

配置后，Claude可以使用这些工具：

工具	参数	说明
`search_messages`	`query`, `maxResults`	使用查询语法搜索Gmail，返回消息元数据
`read_message`	`messageId`	阅读完整的邮件内容，包括正文和附件
`download_attachment`	`messageId`, `attachmentId`, `outputDirectory`, `filename`	将特定附件下载到磁盘

示例克劳德提示：

“在我的Gmail中搜索来自的未读邮件support@example.com"
“读取ID为18d4f2a3b5c6e7f8的消息”
“从该电子邮件下载PDF附件”
“查找我老板上周发来的所有带附件的电子邮件”

🏗️ 建筑学

┌─────────────────────────────────────────────────┐
│              Gmail MCP Server                   │
│                                                 │
│  ┌──────────────┐         ┌─────────────────┐  │
│  │   CLI Mode   │         │   MCP Mode      │  │
│  │              │         │                 │  │
│  │  • auth      │         │  • stdio server │  │
│  │  • search    │         │  • tool calls   │  │
│  │  • read      │         │  • JSON-RPC     │  │
│  │  • download  │         │                 │  │
│  └──────┬───────┘         └────────┬────────┘  │
│         │                          │           │
│         └──────────┬───────────────┘           │
│                    │                           │
│         ┌──────────▼──────────┐                │
│         │  Shared Services    │                │
│         │                     │                │
│         │  • AuthService      │                │
│         │  • GmailService     │                │
│         └──────────┬──────────┘                │
│                    │                           │
│         ┌──────────▼──────────┐                │
│         │    Gmail API v1     │                │
│         │  (Google.Apis)      │                │
│         └─────────────────────┘                │
└─────────────────────────────────────────────────┘

关键部件：

程序cs -具有依赖注入设置的入口点
命令 -CLI命令实现（身份验证、搜索、读取、下载）
服务 -共享业务逻辑（身份验证、Gmail操作）
MCP 服务器 -模型上下文协议服务器和工具定义
模型 -消息和附件的数据结构

🔐 身份验证和安全

OAuth2流

Gmail MCP服务器使用OAuth2进行安全身份验证：

客户端凭据 (gcp-oauth.keys.json)存储在 ~/.gmail-mcp/
使用者同意 通过基于浏览器的谷歌登录获得
访问令牌 本地存储在 ~/.gmail-mcp/token.json
自动刷新 令牌到期时

安全最佳实践

永不承诺 gcp-oauth.keys.json 或 token.json 到版本控制
限制OAuth作用域 达到最低要求（目前使用 GmailReadonlyScope)
审查授予的权限 在 Google帐户设置
轮换凭据 如果你怀疑妥协

设置Google Cloud凭据

详细步骤：

导航到谷歌云控制台
创建新项目：
- 点击“选择项目”>“新建项目”
- 命名它（例如，“Gmail MCP访问”）
- 点击“创建”
启用Gmail API：
- 转到“API和服务”>“库”
- 搜索“Gmail API”
- 点击“启用”
创建OAuth 2.0凭据：
- 转到“API和服务”>“凭据”
- 点击“+创建证书”>“OAuth客户端ID”
- 如果出现提示，请配置OAuth同意屏幕：
  - 用户类型：“外部”
  - 应用程序名称：“Gmail MCP服务器”
  - 用户支持电子邮件：您的电子邮件
  - 开发人员联系人：您的电子邮件
  - 保存并继续完成剩余步骤
- 应用程序类型：“桌面应用程序”
- 名称：“Gmail MCP桌面”
- 点击“创建”
下载凭据：
- 点击下载图标(⬇) 在新创建的OAuth客户端旁边
- 另存为 gcp-oauth.keys.json
- 移动到 ~/.gmail-mcp/gcp-oauth.keys.json
首次身份验证：
```
dotnet-gmail auth
```
- 浏览器自动打开
- 使用您的Google帐户登录
- 授予请求的权限
- 令牌已保存到 ~/.gmail-mcp/token.json

🛠️ 发展

克隆和构建

# Clone repository
git clone https://github.com/yourusername/dotnet-gmail-mcp.git
cd dotnet-gmail-mcp

# Build solution
dotnet build

# Run locally
dotnet run --project src/GmailMcp

本地测试

测试CLI命令

# Build and install locally
dotnet pack src/GmailMcp
dotnet tool install -g --add-source ./src/GmailMcp/nupkg GmailMcp

# Test authentication
dotnet-gmail auth

# Test search
dotnet-gmail search "is:unread" --max-results 5

# Test read
dotnet-gmail read <message-id>

# Uninstall when done
dotnet tool uninstall -g GmailMcp

测试MCP集成

# Start MCP server in one terminal
dotnet-gmail mcp

# In another terminal, send MCP protocol messages via stdin
# (or configure Claude Desktop to use local build)

项目结构

dotnet-gmail-mcp/
├── src/
│   └── GmailMcp/
│       ├── Commands/           # CLI command implementations
│       │   ├── AuthCommand.cs
│       │   ├── SearchCommand.cs
│       │   ├── ReadCommand.cs
│       │   ├── DownloadCommand.cs
│       │   └── McpCommand.cs
│       ├── Services/           # Business logic layer
│       │   ├── IAuthenticationService.cs
│       │   ├── AuthenticationService.cs
│       │   ├── IGmailService.cs
│       │   └── GmailService.cs
│       ├── Models/             # Data structures
│       │   ├── GmailMessage.cs
│       │   └── GmailAttachment.cs
│       ├── Mcp/                # MCP server and tools
│       │   ├── GmailMcpServer.cs
│       │   └── Tools/
│       │       ├── SearchMessagesTool.cs
│       │       ├── ReadMessageTool.cs
│       │       └── DownloadAttachmentTool.cs
│       ├── Program.cs          # Entry point and DI setup
│       └── GmailMcp.csproj     # Project configuration
└── README.md

📋 MCP工具参考

搜索消息

使用Gmail查询语法搜索Gmail邮件。

参数：

query （字符串，必填）-Gmail搜索查询（例如，“发件人：user@example.com“，”主题：会议“，”是：未读“）
maxResults （int，可选）-要返回的最大结果数（默认值：10，最大值：100）

退货： JSON消息对象数组，包含：

id -消息ID
threadId -线程ID
subject -电子邮件主题
from -发件人电子邮件地址
to -收件人电子邮件地址数组
date -ISO 8601格式化日期
hasAttachments -布尔值，指示附件是否存在
attachmentCount -附件数量

例子：

{
  "query": "from:boss@company.com is:unread",
  "maxResults": 5
}

read_message

阅读特定Gmail邮件的完整内容。

参数：

messageId （字符串，必填）-搜索结果中的唯一消息标识符

退货： JSON对象：

id -消息ID
threadId -线程ID
subject -电子邮件主题
from -发件人电子邮件地址
to -收件人电子邮件地址数组
date -ISO 8601格式化日期
body -纯文本电子邮件正文
attachments -附件对象数组 id, filename, mimeType, size

例子：

{
  "messageId": "18d4f2a3b5c6e7f8"
}

下载_附件

将Gmail邮件中的附件下载到本地磁盘。

参数：

messageId （字符串，必填）-包含附件的消息
attachmentId （字符串，必填）-消息中的附件标识符
outputDirectory （字符串，可选）-保存文件的目录（默认：当前目录）
filename （字符串，可选）-自定义文件名（默认：原始文件名）

退货： JSON对象：

filePath -下载文件的完整路径
filename -保存文件的名称
size -文件大小（字节）

例子：

{
  "messageId": "18d4f2a3b5c6e7f8",
  "attachmentId": "ANGjdJ8wK...",
  "outputDirectory": "./downloads",
  "filename": "report.pdf"
}

🤝 贡献

欢迎投稿！请随时提交问题、分叉存储库和创建拉取请求。

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📄 许可证

该项目根据MIT许可证获得许可。看许可证文件以获取详细信息。

🔗 相关项目

模型上下文协议 -MCP规范和SDK
Claude 桌面版 -支持MCP的AI助手
谷歌API。网 -Gmail API客户端库

内置于❤️ 使用。NET与模型上下文协议

使用说明

📧 Gmail MCP服务器

概述

它解决了什么问题

✨ 特性

🚀 快速开始

📦 安装

先决条件

步骤1:谷歌云控制台设置

步骤2：安装工具

步骤3：身份验证

🔧 用法

命令行接口命令模式

认证

搜索邮件

阅读消息

下载附件

MCP模式

快速MCP设置

可用的MCP工具

🏗️ 建筑学

🔐 身份验证和安全

OAuth2流

安全最佳实践

设置Google Cloud凭据

🛠️ 发展

克隆和构建

本地测试

测试CLI命令

测试MCP集成

项目结构

📋 MCP工具参考

搜索消息

read_message

下载_附件

🤝 贡献

📄 许可证

🔗 相关项目

相关 MCP

小红书MCP服务

Figma MCP集成工具

iOS/macOS 构建 MCP 服务器与命令行工具

MCP 协议测试服务器

Flomo笔记服务

小红书内容访问服务