AI导哈

Gmail消息访问服务

一个通过Google Gmail API提供只读访问Gmail的模型上下文协议（MCP）服务器，支持邮件列表查询、详细信息读取和搜索功能。

  • by david-eve-za
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 david-eve-za/gmail-mcp-server

使用说明

Gmail MCP服务器

模型上下文协议（MCP）服务器，通过Google Gmail API提供对Gmail的只读访问。

特性

  • 列出来自Gmail文件夹/标签的邮件
  • 阅读完整的邮件详细信息，包括正文和附件
  • 使用Gmail搜索语法搜索邮件
  • 查看所有Gmail标签及其统计数据
  • 使用OAuth2身份验证的只读访问

先决条件

  1. Node.js 18+和npm
  2. 启用Gmail API的谷歌云项目
  3. OAuth2凭据（客户端ID和客户端机密）

设置

1.获取Google OAuth2凭据

  1. 首选 谷歌云控制台
  2. 创建新项目或选择现有项目
  3. 启用Gmail API：API和服务>库>Gmail API>启用
  4. 创建OAuth2凭据：
    • API和服务>凭据>创建凭据>OAuth客户端ID
    • 应用程序类型：桌面应用程序
    • 名称：Gmail MCP服务器
  5. 复制客户端ID和客户端密码

2.安装依赖项

npm install

3.配置环境变量

创建一个 .env 文件：

GMAIL_CLIENT_ID=your_client_id.apps.googleusercontent.com
GMAIL_CLIENT_SECRET=your_client_secret

备注：重定向URI是使用第一个可用端口（默认值：8080）自动生成的。您可以选择设置 GMAIL_REDIRECT_URI 如果你需要一个特定的端口。

4.建设项目

npm run build

5.使用MCP检查员进行测试

npm run inspect

这将：

  1. 检查中的现有令牌 ~/.gmail-mcp/tokens.json
  2. 如果未找到，请打开浏览器进行OAuth2授权
  3. 授权应用程序访问Gmail
  4. 启动MCP检查器进行测试

用法

服务器提供以下工具：

gmail_list_消息

列出来自Gmail文件夹/标签的邮件。

参数：

  • labelIds （可选）：标签ID数组（默认值：[“INBOX”]）
  • maxResults （可选）：要返回的消息数（默认值：20，最大值：100）
  • pageToken （可选）：分页标记
  • includeSpamTrash （可选）：包括垃圾邮件/垃圾（默认值：false）

gmail_get_message

获取完整的消息详细信息。

参数：

  • messageId （必填）：消息ID
  • format （可选）：“完整”、“元数据”或“最小”（默认值：“元数据”）

gmail_search_message

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

参数：

  • query （必填）：搜索查询（例如，“发件人：john@example.com“，”主题：会议“）
  • maxResults （可选）：结果数（默认值：20）
  • pageToken （可选）：分页标记

gmail_list_labels

列出所有Gmail标签。

无需参数。

gmail_get_label

获取特定标签的详细信息。

参数：

  • labelId （必填）：标签ID

MCP客户端配置

克劳德桌面/克莱恩/OpenAI

  1. 创建或编辑配置文件：

    • macOS/Linux: ~/.config/claude/claude_desktop_config.json
    • 视窗: %APPDATA%\Claude\claude_desktop_config.json

  2. 添加Gmail MCP服务器配置：

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/absolute/path/to/gmail-mcp/build/index.js"
      ],
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id.apps.googleusercontent.com",
        "GMAIL_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

备注：重定向URI是自动生成的。您可以选择设置 GMAIL_REDIRECT_URI 如果你需要一个特定的端口。

Gemini CLI/Gemini CLI

  1. 查找或创建Gemini配置文件：

    • macOS/Linux: ~/.config/gemini/config.json
    • 视窗: %APPDATA%\gemini\config.json

  2. 添加MCP服务器配置：

{
  "mcp": {
    "servers": {
      "gmail": {
        "command": "node",
        "args": [
          "/absolute/path/to/gmail-mcp/build/index.js"
        ],
        "env": {
          "GMAIL_CLIENT_ID": "your_client_id.apps.googleusercontent.com",
          "GMAIL_CLIENT_SECRET": "your_client_secret"
        }
      }
    }
  }
}
  1. 重新启动Gemini CLI

openencode

  1. 查找或创建opencode配置文件：

    • macOS/Linux: ~/.config/opencode/mcp.json
    • 视窗: %APPDATA%\opencode\mcp.json

  2. 添加MCP服务器配置：

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": [
        "/absolute/path/to/gmail-mcp/build/index.js"
      ],
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id.apps.googleusercontent.com",
        "GMAIL_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}
  1. 重新启动opencode应用程序

使用npx（推荐）

您可以直接使用npx而无需安装：

npx -y gmail-mcp-service

在MCP客户端配置中：

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "-y",
        "gmail-mcp-service"
      ],
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id.apps.googleusercontent.com",
        "GMAIL_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

使用npm全局安装

如果您希望全局安装该软件包：

npm install -g @your-scope/gmail-mcp

然后在MCP客户端配置中，使用：

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@your-scope/gmail-mcp"
      ],
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id.apps.googleusercontent.com",
        "GMAIL_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

首次授权

当您首次在任何客户端上使用Gmail MCP服务器时：

  1. 服务器将检查中的现有令牌 ~/.gmail-mcp/tokens.json
  2. 如果没有找到令牌，它将打开您的浏览器进行OAuth2授权
  3. 授权应用程序访问您的Gmail
  4. 令牌存储在本地以供将来使用
  5. 然后，服务器将可供您的MCP客户端使用

发展

# Watch mode for development
npm run dev

# Run tests
npm test

# Build for production
npm run build

CI/CD

该项目使用GitHub Actions进行持续集成和自动发布npm。

运作原理

  1. CI工作流 (.github/workflows/ci.yml):

    • 对每个推送和拉取请求运行 main
    • Node.js 18和20的测试
    • 运行所有测试和TypeScript编译

  2. 发布工作流 (.github/workflows/publish.yml):

    • 运行推送 main 分支
    • 检查版本是否在 package.json 比npm注册表更新
    • 如果版本更改：
      • 运行测试和构建
      • 发布到npm
      • 创建GitHub版本

设置npm发布

要启用自动npm发布：

  1. 转到您的GitHub存储库 设置→ 秘密与变量→ 行动
  2. 点击 新存储库机密
  3. 添加一个名为的秘密 NPM_TOKEN
  4. 使用您的npm身份验证令牌作为值

要创建npm令牌：

  1. 首选 npmjs.com→ 访问令牌
  2. 点击“生成新令牌”→ “自动化”
  3. 复制生成的令牌
  4. 添加为 NPM_TOKEN 在GitHub操作秘密

发布新版本

  1. 更新中的版本 package.json:

    npm version major  # or minor or patch

  2. 承诺并推动 main:

    git commit -am "chore: bump version to X.Y.Z"
git push origin main

  3. GitHub操作将自动：

    • 运行测试
    • 构建项目
    • 发布到npm
    • 创建GitHub版本

安全

  • 令牌存储在本地 ~/.gmail-mcp/tokens.json
  • 仅请求只读Gmail访问
  • 没有共享或传输凭据

许可证

麻省理工学院

相关 MCP