AI导哈

Gmail API集成服务器

一个基于TypeScript构建的生产级Gmail API集成服务器，支持AI代理工具调用，提供完整的Gmail功能。

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

使用说明

Gmail MCP服务器

用于Gmail API集成的可生产的模型上下文协议（MCP）服务器，使用TypeScript构建，专为AI代理工具调用而设计。

🚀 特性

  • 完整的Gmail API集成 -发送、阅读、搜索和管理电子邮件
  • OAuth2身份验证 -基于令牌的安全身份验证，具有自动刷新功能
  • 9综合工具 -为AI代理提供完整的Gmail功能
  • TypeScript实现 -类型安全、可维护的代码
  • 综合测试 -边缘案例处理的测试成功率为83.3%
  • 速率限制 -内置API速率限制和错误处理
  • 生产就绪 -强大的错误处理和安全功能

📋 Gmail工具可用

工具 描述 功能
send_email 发送带附件的电子邮件 撰写、发送、CC/BCC支持
read_emails 读取和列出电子邮件 分页、过滤、元数据
get_email 获取具体的电子邮件详细信息 完整的电子邮件内容、标题
search_emails 高级电子邮件搜索 基于查询的搜索，过滤器
manage_labels 创建/删除电子邮件标签 标签管理，组织
manage_threads 线程操作 标记已读/未读、存档、删除
manage_drafts 草稿电子邮件管理 创建、更新、删除草稿
manage_attachments 处理电子邮件附件 下载、处理附件
email_actions 批量电子邮件操作 批量操作，自动化

🛠️ 先决条件

  • Node.js 18+
  • npm或纱线
  • 谷歌云平台帐户
  • Gmail帐户

📦 安装

  1. 克隆仓库

    git clone <repository-url>
cd gmail-mcp-server

  2. 安装依赖项

    npm install

  3. 构建项目

    npm run build

🔐 Gmail API设置

第一步：创建谷歌云项目

  1. 首选 谷歌云控制台
  2. 创建新项目或选择现有项目
  3. 记下您的项目ID

步骤2：启用Gmail API

  1. 导航至 API和服务 → 图书馆
  2. 搜索“Gmail API”
  3. 点击 启用

步骤3：创建OAuth2凭据

  1. 首选 API和服务 → 凭证
  2. 点击 创建凭证 → OAuth客户端ID
  3. 选择 桌面应用程序
  4. 下载JSON文件
  5. 注意 client_id 和 client_secret

步骤4：配置OAuth同意屏幕

  1. 首选 API和服务 → OAuth 授权界面
  2. 选择 外部 用户类型
  3. 填写应用程序信息：
    • 应用程序名称： Gmail MCP Server
    • 用户支持电子邮件： your-email@gmail.com
    • 开发者联系人： your-email@gmail.com
  4. 添加作用域：
    • https://www.googleapis.com/auth/gmail.readonly
    • https://www.googleapis.com/auth/gmail.send
    • https://www.googleapis.com/auth/gmail.modify
    • https://www.googleapis.com/auth/gmail.compose
  5. 添加测试用户（您的电子邮件地址）
  6. 保存配置

步骤5：生成刷新令牌

  1. 设置环境变量 （替换为您的值）：

    export GMAIL_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GMAIL_CLIENT_SECRET="your-client-secret"

  2. 生成刷新令牌:

    npm run generate-token

  3. 按照提示操作:

    • 出现提示时输入您的客户ID
    • 出现提示时输入您的客户端密码
    • 浏览器将打开进行授权
    • 为您的Gmail帐户授予权限
    • 从URL复制授权码
    • 将其粘贴回终端
    • 复制生成的 GMAIL_REFRESH_TOKEN

  4. 设置刷新令牌:

    export GMAIL_REFRESH_TOKEN="your-refresh-token"

🚀 用法

基本用法

  1. 设置所有环境变量:

    export GMAIL_CLIENT_ID="your-client-id.apps.googleusercontent.com"
export GMAIL_CLIENT_SECRET="your-client-secret"
export GMAIL_REFRESH_TOKEN="your-refresh-token"

  2. 运行服务器:

    npm start

  3. 测试连接:

    npm test

工具使用示例

// Send an email
const result = await server.execute('send_email', {
  to: 'recipient@example.com',
  subject: 'Test Email',
  body: 'Hello from Gmail MCP Server!',
  isHtml: false
});

// Read emails
const emails = await server.execute('read_emails', {
  maxResults: 10,
  query: 'is:unread'
});

// Search emails
const searchResults = await server.execute('search_emails', {
  query: 'from:important@example.com',
  maxResults: 5
});

🧪 测试

运行所有测试

npm test

运行结构测试（无需凭据）

npm run test:structure

观看模式

npm run test:watch

预期测试结果

  • ✅ 凭证验证 -通过
  • ✅ 连接测试 -通过
  • ✅ 电子邮件发送 -通过
  • ✅ 电子邮件阅读 -通过
  • ✅ 电子邮件搜索 -通过
  • ✅ 线程管理 -通过
  • ✅ 速率限制 -通过
  • ✅ 边缘案例 -通过
  • ✅ 错误处理 -通过

📁 项目结构

gmail-mcp-server/
├── src/
│   ├── gmail-true-mcp.ts      # Main Gmail MCP server
│   ├── true-json-base.ts      # Base MCP server class
│   ├── server-manager.ts      # Server management interfaces
│   └── gmail-test.ts          # Test suite
├── docs/
│   └── GMAIL_MCP_DOCUMENTATION.md  # Detailed API documentation
├── package.json               # Dependencies and scripts
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

🔧 配置

环境变量

变量 描述 必填
GMAIL_CLIENT_ID 来自Google Cloud的OAuth2客户端ID 是
GMAIL_CLIENT_SECRET 来自Google Cloud的OAuth2客户端机密 是
GMAIL_REFRESH_TOKEN OAuth2刷新令牌（已生成） 是

速率限制

服务器包括内置的速率限制：

  • 默认：每100秒100个请求
  • 可配置的：调整 gmail-true-mcp.ts
  • 自动：处理Gmail API配额

🛡️ 安全

  • OAuth2身份验证 -行业标准安全身份验证
  • 令牌刷新 -自动访问令牌续订
  • 凭证保护 -从不记录敏感信息
  • 速率限制 -防止API配额耗尽
  • 错误处理 -优雅的故障处理

📚 文档

  • api参考：参见 docs/GMAIL_MCP_DOCUMENTATION.md
  • 工具架构：详细的参数规格
  • 错误代码：全面的错误处理指南
  • 例子：实际使用示例

🚀 部署

生产检查表

  • []建立谷歌云项目
  • []配置OAuth同意屏幕
  • []生成刷新令牌
  • []设置环境变量
  • []运行测试套件
  • []部署到您的基础架构

环境设置

# Production environment variables
export GMAIL_CLIENT_ID="your-production-client-id"
export GMAIL_CLIENT_SECRET="your-production-client-secret"
export GMAIL_REFRESH_TOKEN="your-production-refresh-token"
export NODE_ENV="production"

🤝 贡献

  1. 复刻仓库
  2. 创建要素分支
  3. 进行更改
  4. 添加测试
  5. 提交拉取请求

📄 许可证

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

🆘 支持

对于问题和疑问：

  1. 检查文档
  2. 查看测试套件
  3. 检查谷歌云控制台配置
  4. 验证OAuth同意屏幕设置

🎯 后续步骤

此Gmail MCP服务器演示了为AI代理工具调用构建企业级MCP服务器的能力。该实现可以用作为其他服务构建MCP服务器的模板，例如：

  • GitHub API
  • 松弛API
  • API通知
  • Google Drive API
  • 以及500+其他服务

内置于❤️ 用于AI代理集成

相关 MCP