使用说明

Gmail MCP服务器

本地人主控程序为Claude提供本机工具级访问权限的服务器到 Gmail。通过stdio传输在本地运行——所有令牌和凭据都保留在您的计算机上。

先决条件

Python 3.14+
紫外线用于依赖关系管理
启用Gmail API的Google帐户

快速开始

# Clone the repo
git clone https://github.com/stevesimpson418/gmail-mcp-server.git
cd gmail-mcp-server

# Install dependencies (creates .venv/ in the project directory)
uv sync

紫外线新手？ uv sync 读取 pyproject.toml，创建了一个 .venv/ virtualenv内部项目文件夹，并将所有依赖项安装到其中。您不需要激活它-- uv run <command> 自动处理。

设置Gmail

1.创建谷歌云项目

去谷歌云控制台并创建一个新项目（或选择一个现有的）。

2.启用Gmail API

引导到 API和服务>库，搜索 Gmail API，然后单击启用.

3.配置OAuth同意屏幕

在创建凭据之前，Google要求您配置OAuth同意屏幕。首选 API和服务>OAuth同意屏幕 （或 谷歌认证平台 如果提示）。

点击 开始使用 （或 配置同意屏幕)
填写必填字段：
- 应用程序名称 --一个供您参考的名称（例如“Gmail MCP服务器”）
- 用户支持电子邮件 --您的电子邮件地址
选择一个观众:
- 内部的 --仅当您在Google Workspace组织中时可用
- 外部 --为个人Google帐户选择此项。应用程序开始于 测试模式，这对个人使用很好——你只需要将自己添加为测试用户
联系方式 --您的电子邮件（谷歌使用此邮件通知您项目更改）
点击保存

关于测试模式： 测试模式下的外部应用程序仅限于您明确指定的用户添加到测试用户列表中。这对于本地MCP服务器来说非常好——你只需要你自己的账户。测试用户的代币在7天后过期，需要重新同意。如果这如果变得不方便，您可以发布应用程序（敏感范围不需要验证在测试模式下与少于100个用户一起使用，但发布会取消7天的到期日）。

4.添加测试用户

首选 API和服务>OAuth同意屏幕>测试用户 （或观众在新 Google Auth Platform UI）并添加您的Google帐户电子邮件地址。

5.添加OAuth作用域

首选 API和服务>OAuth同意屏幕>范围 （或 数据访问 在新UI中）并添加以下范围：

范围	为什么需要它
`https://www.googleapis.com/auth/gmail.modify`	阅读邮件、修改标签（存档、星号、标记已读/未读、应用/删除标签）、管理草稿、发送电子邮件以及将邮件移至垃圾箱。这是涵盖所有服务器操作的最小单一作用域——更窄的作用域，如 `gmail.readonly` 或 `gmail.send` 不要覆盖标签修改或垃圾。

此服务器确实不请求 mail.google.com （完全无限制访问）-- gmail.modify 作用域为读/写操作，不能永久删除消息。

6.创建OAuth 2.0凭据

首选 API和服务>凭据
点击 创建凭据>OAuth客户端ID
应用程序类型： 桌面应用
给它起个名字作为参考（例如“Gmail MCP——我的笔记本电脑”）
点击创建那么 下载JSON
将文件另存为 credentials/gmail_credentials.json 在这个项目中

安全说明： 这 credentials/ 目录被gitignored--您的凭据和令牌永远不会提交到存储库。

7.运行OAuth同意流

uv run gmail-mcp-auth

将打开一个浏览器窗口——使用您作为测试用户添加的Google帐户登录，然后授予请求的权限。令牌保存到 credentials/token.json 和在此之后自动刷新。

要使用自定义路径，请执行以下操作：

uv run gmail-mcp-auth --credentials /path/to/creds.json --token /path/to/token.json

添加到Claude桌面

将以下内容添加到您的Claude Desktop配置中(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）。

提示： 跑 uv run which python 从项目目录中获取 command.

{
  "mcpServers": {
    "gmail": {
      "command": "/Users/you/gmail-mcp-server/.venv/bin/python",
      "args": ["-m", "gmail_mcp.server"],
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/Users/you/gmail-mcp-server/credentials/gmail_credentials.json",
        "GMAIL_TOKEN_PATH": "/Users/you/gmail-mcp-server/credentials/token.json"
      }
    }
  }
}

这 env 块告诉服务器在运行时在何处查找凭据。不 .env 文件是 required——配置直接传递这些值。

保存后重新启动Claude Desktop。您应该在工具菜单中看到所有Gmail工具。

添加到Claude代码CLI

使用 claude mcp add 注册服务器的命令。这适用于任何目录。

claude mcp add --scope user gmail-mcp-server \
  --transport stdio \
  --env GMAIL_CREDENTIALS_PATH=/path/to/gmail-mcp-server/credentials/gmail_credentials.json \
  --env GMAIL_TOKEN_PATH=/path/to/gmail-mcp-server/credentials/token.json \
  -- /path/to/gmail-mcp-server/.venv/bin/python -m gmail_mcp.server

替换 /path/to/gmail-mcp-server 使用克隆仓库的实际路径。

提示： 跑 uv run which python 从项目目录中获取确切信息 .venv/bin/python 命令的路径。

这 --scope user 标志保存到 ~/.claude.json 因此，服务器在所有项目中都是可用的。没有它，命令默认为本地作用域（绑定到您运行它的任何目录）。要将其范围改为单个项目，请使用 --scope project 它写入 .mcp.json 在项目根。

要验证服务器是否已注册：

claude mcp list

添加后重新启动Claude Code。Gmail工具应该出现在 /mcp 菜单。

注： Claude Code CLI使用与Claude Desktop不同的配置。这 claude mcp add 命令是注册MCP服务器的推荐方式——不要将它们添加到 ~/.claude/settings.json 因为该文件仅用于权限和挂钩。

更新

要获取最新版本并更新依赖关系，请执行以下操作：

cd /path/to/gmail-mcp-server
git pull
uv sync

更新后重新启动Claude Desktop或Claude Code CLI。

如果新版本更改了OAuth范围，您需要通过运行以下命令重新同意 uv run gmail-mcp-auth 再一次。

可用工具

工具	说明
`search_gmail(query, max_results?)`	使用Gmail查询语法搜索邮件（例如。 `is:unread in:inbox`)
`read_gmail_message(message_id)`	阅读包括正文在内的完整消息
`read_gmail_thread(thread_id)`	阅读一个线程中的所有消息
`list_gmail_labels()`	列出所有标签（系统和用户创建）
`list_gmail_attachments(message_id)`	列出邮件中的附件
`read_gmail_attachment(message_id, attachment_id, filename, mime_type)`	内联读取附件内容
`archive_gmail_messages(message_ids)`	存档邮件（从收件箱中删除）
`bulk_archive_gmail(query)`	在一次通话中搜索并存档所有匹配的消息
`apply_gmail_label(message_ids, label_name)`	为邮件应用标签
`remove_gmail_label(message_ids, label_name)`	从邮件中删除标签
`create_gmail_label(name, text_color?, background_color?)`	创建新标签
`mark_gmail_read(message_ids)`	将邮件标记为已读
`mark_gmail_unread(message_ids)`	将邮件标记为未读
`star_gmail_message(message_ids)`	明星留言
`mark_gmail_important(message_ids)`	将消息标记为重要
`create_gmail_draft(to, subject, body, thread_id?, cc?)`	创建电子邮件草稿
`send_gmail(to, subject, body, cc?)`	直接发送电子邮件
`send_gmail_draft(draft_id)`	发送以前创建的草稿
`trash_gmail_messages(message_ids)`	将邮件移至垃圾箱（可恢复30天）

用法示例

对收件箱进行分类：

1. search_gmail(query="is:unread in:inbox")          → see what's new
2. read_gmail_message(message_id="msg_123")           → read the full message
3. archive_gmail_messages(message_ids=["msg_123"])     → archive after reading

大规模清理：

bulk_archive_gmail(query="from:noreply@marketing.com in:inbox")
bulk_archive_gmail(query="is:unread in:inbox older_than:7d subject:newsletter")

起草答复：

create_gmail_draft(
    to="alice@example.com",
    subject="Re: Meeting",
    body="Sounds good, see you then!",
    thread_id="thread_abc"
)

发展

# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest -v

# Run tests with coverage
uv run pytest --cov=gmail_mcp --cov-report=term-missing

# Lint
uv run ruff check src/ tests/

# Format
uv run ruff format src/ tests/

# Install git hooks
lefthook install

本地 `.env` 文件

在Claude Desktop/Code之外手动运行服务器时（例如，用于开发或调试），您可以创建 .env 项目根目录中的文件，以便服务器拾取不传递环境变量的凭据路径：

GMAIL_CREDENTIALS_PATH=credentials/gmail_credentials.json
GMAIL_TOKEN_PATH=credentials/token.json

这只是当地发展所需要的。Claude桌面和Claude代码CLI配置通过直接传递这些值 env 块。

包装与配送

此服务器目前通过git作为源代码分发。要安装：

git clone https://github.com/stevesimpson418/gmail-mcp-server.git
cd gmail-mcp-server
uv sync

这是目前本地stdio MCP服务器的标准分发模型。该项目是已经配置为通过掀背车进行车轮制造，因此未来的分销选项包括：

PyPI --发布到PyPI，然后安装 uv tool install gmail-mcp-server 或 pip install gmail-mcp-server。需要向CI添加发布工作流。
uvx --一旦在PyPI上， uvx gmail-mcp-server 在不克隆仓库的情况下运行服务器。 Claude Desktop/Code配置将指向uvx管理的二进制文件，而不是本地文件 .venv.

发布

此项目使用请释放用于自动化版本控制和发布。版本由以下因素决定约定式提交:

fix: 提交bump 补丁版本（例如0.1.0→ 0.1.1)
feat: 提交bump 次要的 版本（例如0.1.1→ 0.2.0)
BREAKING CHANGE 在提交页脚中颠簸 主要的 版本

当承诺土地 main，请打开（或更新）一个发布PR，该PR：

将版本插入 pyproject.toml
更新 CHANGELOG.md 带有分组条目

合并Release PR会自动创建一个git标签和GitHub Release。

许可证

麻省理工学院

使用说明

Gmail MCP服务器

先决条件

快速开始

设置Gmail

1.创建谷歌云项目

2.启用Gmail API

3.配置OAuth同意屏幕

4.添加测试用户

5.添加OAuth作用域

6.创建OAuth 2.0凭据

7.运行OAuth同意流

添加到Claude桌面

添加到Claude代码CLI

更新

可用工具

用法示例

发展

本地 .env 文件

包装与配送

发布

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器

本地 `.env` 文件