使用说明

Gmail MCP服务器

一个模型上下文协议（MCP）服务器，通过17个强大的工具为AI助手提供全面的Gmail访问。

特性

17个Gmail工具：发送、阅读、搜索、管理电子邮件、草稿、标签、过滤器和设置
Markdown导出：自动将大型结果集保存到grep友好的markdown文件中
安全OAuth 2.0：带有自动令牌刷新的Google身份验证
MCP资源：智能LLM交互的实时身份验证状态
完整TypeScript：使用Zod模式验证进行类型安全
生产就绪：全面的错误处理和Gmail API最佳实践

快速开始

1.安装

npm install
npm run build

2.设置Google OAuth

首选谷歌云控制台
创建项目并启用 Gmail API
创建 OAuth 2.0凭据 （桌面应用程序类型）
下载并另存为 credentials.json:
- 推荐: ~/.config/mcp-gmail/credentials.json （从任何目录工作）
- 替代：项目根（向后兼容）

📖 详细设置：参见 docs/AUTHENTION_GUIDE.md

3.身份验证

npm run auth

这将打开您的浏览器以与Google进行身份验证，并将令牌保存到 ~/.config/mcp-gmail/token.json.

4.配置MCP客户端

添加到您的MCP客户端（例如，Claude Desktop配置）：

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-gmail/dist/index.js"]
    }
  }
}

或者在以下情况下使用bin命令 npm link:

{
  "mcpServers": {
    "gmail": {
      "command": "mcp-gmail"
    }
  }
}

可用工具

基本工具

send电子邮件 -发送带有HTML、CC/BCC和附件的电子邮件
search消息 -使用Gmail查询语法进行搜索
list消息 -列出带有筛选器的邮件
getMessage -阅读完整消息内容

电子邮件管理

getThread -获取对话线索
创建草稿 / sendDraft -草案管理
修改消息 -更改标签（已读/未读、星号、存档）
batch修改 -批量操作（最多1000条消息）
获取附件 -下载附件

组织

list标签 / 创建标签 -标签管理
list筛选器 / 创建过滤器 -电子邮件过滤自动化

设置

getSettings -帐户设置
updateSignature -电子邮件签名
setVacation响应器 -自动回复配置

📖 全参考: docs/TOOLS_REFERENCE.md

用法示例

搜索和阅读电子邮件

// Search for emails
await searchMessages({
  query: "from:example@gmail.com is:unread",
  maxResults: 10
});

// Read a message
await getMessage({
  messageId: "abc123",
  format: "full"
});

发送邮件

await sendEmail({
  to: "recipient@example.com",
  subject: "Hello",
  body: "<h1>Test</h1><p>Email body</p>",
  isHtml: true,
  attachments: [
    { filename: "report.pdf", path: "/path/to/file.pdf" }
  ]
});

管理邮件

// Mark as read and archive
await modifyMessage({
  messageId: "abc123",
  addLabelIds: ["STARRED"],
  removeLabelIds: ["UNREAD", "INBOX"]
});

// Bulk archive
await batchModify({
  messageIds: ["id1", "id2", "id3"],
  removeLabelIds: ["INBOX"]
});

Markdown导出功能

默认情况下, searchMessages, listMessages，以及 getThread 自动将结果保存到markdown文件，而不是内联返回数据。这节省了令牌，并允许使用grep/awk进行高效解析。

默认行为

// Results saved to ~/.mcp-gmail/exports/search-messages/YYYY-MM-DD-description.md
await searchMessages({
  query: "from:boss@company.com",
  outputDescription: "emails-from-boss"  // Optional, auto-generated if not provided
});

// Returns:
// {
//   success: true,
//   savedToFile: true,
//   filePath: "~/.mcp-gmail/exports/search-messages/2025-11-10-emails-from-boss.md",
//   count: 247,
//   format: "markdown"
// }

选择加入内联结果

集 returnInline: true 直接获得结果：

await searchMessages({
  query: "is:unread",
  returnInline: true  // Get JSON response instead of file
});

Grep友好格式

Markdown文件的结构便于搜索：

# Find all senders
grep "^**From:**" ~/.mcp-gmail/exports/search-messages/2025-11-10-emails.md

# Find emails with attachments
grep "^**Attachments:** Yes" ~/.mcp-gmail/exports/search-messages/*.md

# Count unread emails in a search
grep "^**Labels:**.*UNREAD" ~/.mcp-gmail/exports/search-messages/2025-11-10-*.md | wc -l

# Get full email by sender
grep -A 10 "^**From:** boss@company.com" ~/.mcp-gmail/exports/search-messages/*.md

导出目录结构

~/.mcp-gmail/
  exports/
    search-messages/
      2025-11-10-emails-from-boss.md
      2025-11-10-unread-urgent.md
    list-messages/
      2025-11-10-inbox-last-week.md
    get-thread/
      2025-11-10-project-discussion.md

备注：导出文件包含个人电子邮件数据，并通过以下方式自动排除在版本控制之外 .gitignore.

身份验证资源

服务器提供 gmail://auth-status LLM可以读取的资源：

操作前检查身份验证状态
引导用户完成设置
提供上下文感知的故障排除

项目结构

mcp-gmail/
├── src/
│   ├── tools/              # 17 Gmail tools
│   ├── resources/          # MCP resources (auth-status)
│   ├── auth/               # OAuth 2.0 flow
│   └── utils/              # MIME builder, parsers, error handling
├── docs/                   # Documentation
├── scripts/                # Utility scripts
└── dist/                   # Compiled output

配置

凭证文件（开发）

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "redirect_uris": ["http://localhost"]
  }
}

环境变量（生产）

export GOOGLE_CLIENT_ID="YOUR_CLIENT_ID"
export GOOGLE_CLIENT_SECRET="YOUR_CLIENT_SECRET"
export GOOGLE_REDIRECT_URI="http://localhost"

故障排除

“未配置OAuth凭据”

确保 credentials.json 存在于 ~/.config/mcp-gmail/ 或项目根
或设置环境变量（请参阅配置）

“访问被阻止：此应用程序的请求无效”

在OAuth同意屏幕中将自己添加为测试用户
验证Gmail API是否已启用

令牌错误

rm ~/.config/mcp-gmail/token.json
npm run auth

📖 更多帮助: docs/AUTHENTION_GUIDE.md

文档

QUICKSTART.md -5分钟设置指南
身份验证_GUIDE.md -带有截图的OAuth设置
工具_参考.md -完整的API参考
LOGI_FLOW.md -技术认证深度挖掘

发展

# Build
npm run build

# Test
npm test

# Validate MCP
mcp validate

# Lint
npm run lint

安全

OAuth令牌存储在 ~/.config/mcp-gmail/ （用户主目录）
自动令牌刷新
细粒度OAuth作用域
永不承诺 credentials.json

API限值

Gmail API配额：

250个配额单位/用户/秒
1B配额单位/天
Google Cloud控制台中的监视器

贡献

分叉存储库
创建要素分支
添加测试和文档
提交拉取请求

许可证

MIT许可证

链接

Gmail API: https://developers.google.com/gmail/api
MCP协议: https://modelcontextprotocol.io
问题: https://github.com/dennisonbertram/mcp-gmail/issues

内置于 mcp框架, 谷歌蜜蜂和TypeScript。