使用说明

谷歌mcp

用于谷歌服务的MCP服务器——Gmail、谷歌云端硬盘和谷歌日历。

每个服务都作为单独的服务运行模型上下文协议服务器，专为与AI编码助手和MCP兼容客户端一起使用而设计。

使用单个二进制文件支持多个Google帐户（例如“个人”、“工作”）。

特性

Gmail --搜索、阅读、发送（带附件）、草稿、标签、过滤器、垃圾/取消跟踪、历史记录、以别名发送、假期设置、跨服务驱动器集成
Google 云端硬盘 --搜索、列表、阅读、上传、复制、移动、共享、权限、共享驱动器、修订、更改跟踪、垃圾箱
Google 日历 --列表、创建、更新、删除事件、管理邀请、忙/闲查询、日历CRUD、共享（ACL）、订阅、颜色、事件上的驱动器文件附件
多账户 --使用 account="all" 一次查询所有帐户
每台服务服务器 --只跑你需要的东西
工具过滤 — --read-only, --enable, --disable 用于粒度控制

安装

自制（macOS/Linux）

brew install greatliontech/tap/google-mcp

GitHub 发布

从下载预构建的二进制文件发布页面适用于Linux、macOS和Windows（amd64/arm64）。

来源

需要转到1.25+.

go install github.com/greatliontech/google-mcp@latest

或者克隆并构建：

git clone https://github.com/greatliontech/google-mcp.git
cd google-mcp
go build -o ~/.local/bin/google-mcp .

谷歌云设置

在使用google mcp之前，您需要来自google Cloud项目的OAuth凭据。这是一次性设置。

1.创建谷歌云项目

首选谷歌云控制台
单击顶部的项目下拉列表并选择 新项目
为其命名（例如“MCP”）并单击创建
确保在项目下拉列表中选择了新项目

2.启用API

为要使用的服务启用API：

Gmail API — 在此处启用
Google Drive API — 在此处启用
谷歌日历API — 在此处启用

3.配置OAuth同意屏幕

首选 OAuth 同意屏幕
点击开始
填写必填字段：
- 应用程序名称：例如“谷歌mcp”
- 用户支持电子邮件：选择您的电子邮件
- 观众：选择外部
接受默认设置并单击创建
在...之下观众 > 测试用户，单击 添加用户
添加您计划在谷歌mcp中使用的每个谷歌帐户的电子邮件地址（例如您的个人Gmail、工作帐户等）
点击保存

注：当应用程序处于“测试”状态时，只有列为测试用户的用户才能授权。这对个人使用很好——你不需要发布或验证应用程序。

4.添加OAuth作用域

首选数据访问（在API和服务>数据访问下）
点击 添加或删除作用域
根据您需要的服务添加以下范围：

服务	范围	描述
Gmail	`https://mail.google.com/`	完全邮箱访问权限（读取、发送、删除、设置）
Gmail	`https://www.googleapis.com/auth/gmail.settings.basic`	管理过滤器和其他基本设置
Gmail	`https://www.googleapis.com/auth/drive`	附加驱动器文件并将附件保存到驱动器
驾驶	`https://www.googleapis.com/auth/drive`	完全访问谷歌云端硬盘
日历	`https://www.googleapis.com/auth/calendar`	完全访问谷歌日历（活动、日历、共享）
日历	`https://www.googleapis.com/auth/drive`	解析事件附件的驱动器文件元数据

点击更新然后保存

5.创建OAuth凭据

首选凭证
点击 创建凭据 > OAuth客户端ID
选择 桌面应用 作为应用程序类型
给它起个名字（例如“谷歌mcp”）
点击创建
点击 下载JSON （或新客户端ID旁边的下载图标）
将文件另存为 credentials.json 在您的配置目录中：

平台	默认配置目录
Linux	`~/.config/google-mcp`
macOS	`~/Library/Application Support/google-mcp`
窗户	`%AppData%\google-mcp`

覆盖 --config-dir.

帐户设置

添加您要使用的每个Google帐户。这个名字就是你自己的标签。

# Add accounts
google-mcp auth add personal
google-mcp auth add work

# List configured accounts
google-mcp auth list

# Remove an account
google-mcp auth remove work

当你奔跑时 auth add，将打开一个浏览器窗口，显示谷歌的OAuth同意流。授权后，令牌将保存在本地。

重要提示： 您添加的每个帐户都必须在 OAuth 同意屏幕（见上述步骤3.6）。

用法

每个服务都作为单独的MCP服务器在stdio上运行：

google-mcp gmail      # Start Gmail MCP server
google-mcp drive      # Start Google Drive MCP server
google-mcp calendar   # Start Google Calendar MCP server

MCP客户端配置

克劳德代码

添加 ~/.claude.json 或者你的项目 .mcp.json:

{
  "mcpServers": {
    "gmail": {
      "command": "google-mcp",
      "args": ["gmail"]
    },
    "drive": {
      "command": "google-mcp",
      "args": ["drive"]
    },
    "calendar": {
      "command": "google-mcp",
      "args": ["calendar"]
    }
  }
}

要使用只读模式、工具筛选或本地文件访问，请向 args 数组：

{
  "mcpServers": {
    "gmail": {
      "command": "google-mcp",
      "args": ["gmail", "--read-only"]
    },
    "drive": {
      "command": "google-mcp",
      "args": ["drive", "--disable", "delete_file,empty_trash"]
    }
  }
}

要启用本地文件附件和上传，请执行以下操作：

{
  "mcpServers": {
    "gmail": {
      "command": "google-mcp",
      "args": ["gmail", "--allow-read-dir", "/home/user/documents", "--allow-write-dir", "/home/user/downloads"]
    },
    "drive": {
      "command": "google-mcp",
      "args": ["drive", "--allow-read-dir", "/home/user/documents", "--allow-write-dir", "/home/user/downloads"]
    }
  }
}

开源代码

添加 ~/.config/opencode/opencode.json:

{
  "mcp": {
    "gmail": {
      "type": "local",
      "command": ["google-mcp", "gmail"]
    },
    "drive": {
      "type": "local",
      "command": ["google-mcp", "drive"]
    },
    "calendar": {
      "type": "local",
      "command": ["google-mcp", "calendar"]
    }
  }
}

旗帜

全球旗帜 （所有子命令）：

--config-dir     Override config directory (default: ~/.config/google-mcp)
--credentials    Override path to credentials.json

服务器标志 （gmail、驱动器、日历）：

--read-only        Only expose read-only tools (no mutations)
--enable           Whitelist of tool names to expose (comma-separated)
--disable          Blacklist of tool names to hide (comma-separated)
--allow-read-dir   Local directories to allow reading from (repeatable)
--allow-write-dir  Local directories to allow reading and writing (repeatable)

--enable 和 --disable 是相互排斥的。当 --read-only 设置， --enable/--disable 仅对只读子集进行操作。

示例：

# Read-only Gmail server (no send, modify, delete, etc.)
google-mcp gmail --read-only

# Only expose search and read tools
google-mcp gmail --enable search_messages,read_message,read_thread,list_labels

# Everything except delete
google-mcp drive --disable delete_file,empty_trash

# Read-only drive, but exclude shared drive tools
google-mcp drive --read-only --disable list_shared_drives,get_shared_drive

# Enable local file access for email attachments
google-mcp gmail --allow-read-dir /home/user/documents --allow-read-dir /home/user/exports

# Enable local file upload to Drive
google-mcp drive --allow-read-dir /home/user/documents

跨服务集成

Gmail和日历服务器包括内置的Google Drive集成。服务器端的所有数据流——文件内容永远不会进入LLM上下文窗口。

电子邮件附件

send_message, create_draft，以及 update_draft 支持三种附件：

内联附件 --直接在 attachments 领域
驱动器附件 --Google Drive中的文件ID drive_attachments 字段，已在服务器端解析
本地附件 --中的本地文件路径 local_attachments 字段，从允许的目录读取

驱动器附件可以引用以下文件 任何已配置的帐户，而不仅仅是发送帐户。例如，你可以从你的个人Gmail发送一封电子邮件，并从你的工作驱动器中附加一个文件——即使是Gmail的web UI也无法做到这一点。

send_message(
  account="personal",
  to="colleague@example.com",
  subject="Q4 Report",
  body="See attached.",
  drive_attachments=[{drive_account: "work", file_id: "abc123"}]
)

服务器从内存中的驱动器获取文件字节，将其编码为MIME附件，并通过Gmail发送。LLM只看到文件ID和“消息已发送”确认。

本地文件访问

本地文件访问权限为 仅限选择加入 默认情况下禁用。使用 --allow-read-dir 或 --allow-write-dir 以授予MCP服务器对特定目录的访问权限。路径控制由以下人员执行 os.Root （转到1.25+）在内核级别-- ../ 遍历和符号链接转义被操作系统阻止。

--allow-read-dir 授予只读访问权限（用于上传/附加本地文件）
--allow-write-dir 授予读写权限（还允许将文件保存到磁盘）

启用后，有两个便利工具-- list_local_files 和 read_local_file --自动添加，以便LLM可以浏览和读取允许目录中的文件。所有接受本地文件路径的工具在其描述中都包括配置的目录路径和访问模式，因此LLM始终知道哪些目录可用。

上传和附加本地文件

# Gmail: attach local files to emails
google-mcp gmail --allow-read-dir ~/documents

send_message(
  account="personal",
  to="colleague@example.com",
  subject="Report",
  body="See attached.",
  local_attachments=[{path: "reports/q4.pdf"}]
)

# Drive: upload local files
google-mcp drive --allow-read-dir ~/documents

upload_file(account="personal", local_path="reports/q4.pdf")

本地附件也支持 create_draft 和 update_draft.

将文件保存到磁盘

随着 --allow-write-dir，the read_file （驾驶）和 get_attachment （Gmail）工具接受 save_to 现场。设置后，文件将写入磁盘 内容从不进入对话 --没有尺寸限制。

# Drive: download a file to disk
google-mcp drive --allow-write-dir ~/downloads

read_file(account="personal", file_id="...", save_to="report.pdf")

# Gmail: save an attachment to disk
google-mcp gmail --allow-write-dir ~/downloads

get_attachment(account="work", message_id="...", attachment_id="...", save_to="invoice.pdf")

浏览本地文件

当配置任何目录时， list_local_files 和 read_local_file 工具会自动出现在所有服务器上：

# List files in the allowed directory
list_local_files()                     # list root
list_local_files(path="subdir")        # list subdirectory

# Read a text file (512 KB limit, binary files rejected)
read_local_file(path="notes.txt")

将附件保存到驱动器

这 save_attachment_to_drive 该工具将Gmail附件直接传输到Google云端硬盘。与Drive附件一样，它支持跨帐户传输——将一个帐户收件箱中的附件保存到另一个帐户的Drive。

save_attachment_to_drive(
  account="work",
  message_id="...",
  attachment_id="...",
  drive_account="personal",
  file_name="invoice.pdf"
)

日历活动附件

create_event 和 update_event 支持a drive_attachments 字段，用于将Google Drive文件附加到日历事件（会议议程、甲板、笔记）。只解析文件元数据，不下载文件字节。

与电子邮件附件一样，这些附件支持跨帐户引用：

create_event(
  account="work",
  summary="Quarterly Review",
  start_time="2024-01-15T14:00:00-05:00",
  end_time="2024-01-15T15:00:00-05:00",
  drive_attachments=[{drive_account: "work", file_id: "abc123"}]
)

更新事件时，驱动器附件将附加到任何现有附件。

可用工具

Gmail（36个工具）

工具	说明
`list_accounts`	列出已配置的帐户
`get_profile`	获取电子邮件地址、消息/线程数
`search_messages`	使用Gmail查询语法搜索邮件
`read_message`	按ID读取完整消息内容
`list_threads`	列出线程（基于线程的浏览）
`read_thread`	阅读一个线程中的所有消息
`modify_thread`	在整个螺纹上添加/删除标签
`trash_thread`	将线程移到垃圾桶
`untrash_thread`	从回收站还原线程
`delete_thread`	永久删除线程（不可逆）
`send_message`	发送带有附件的电子邮件（内联base64或来自Google Drive）
`modify_messages`	批量添加/删除邮件上的标签
`trash_message`	将邮件移至垃圾箱
`untrash_message`	从回收站还原邮件
`delete_message`	永久删除邮件（不可逆）
`batch_delete_messages`	永久删除多条消息（不可逆）
`list_labels`	列出所有标签
`get_label`	获取标签详细信息（未读/总计数）
`create_label`	创建自定义标签
`update_label`	重命名标签或更改可见性
`delete_label`	删除自定义标签
`get_attachment`	下载附件（或保存到本地磁盘 `save_to`)
`list_history`	跟踪自历史ID以来的邮箱更改
`list_filters`	列出收件箱筛选器（规则）
`create_filter`	创建收件箱筛选器
`delete_filter`	删除收件箱筛选器
`list_send_as`	以别名发送列表
`get_vacation`	获取假期/自动回复设置
`update_vacation`	更新假期/自动回复设置
`create_draft`	创建草稿（带附件）
`list_drafts`	列出草稿
`get_draft`	按ID获取草稿
`update_draft`	更新草稿（带附件）
`delete_draft`	删除草稿
`send_draft`	发送现有草稿
`save_attachment_to_drive`	将Gmail附件直接保存到Google云端硬盘（服务器端）

谷歌云端硬盘（27工具）

工具	说明
`list_accounts`	列出已配置的帐户
`search_files`	使用驱动器查询语法搜索文件
`list_files`	列出文件，可选择在文件夹中
`get_file`	获取文件元数据
`read_file`	读取/下载文件内容（或保存到本地磁盘 `save_to`)
`upload_file`	上传新文件
`update_file`	更新文件元数据（重命名、描述）
`delete_file`	删除文件（垃圾或永久）
`create_folder`	创建文件夹
`move_file`	将文件移动到其他文件夹
`copy_file`	复制文件
`share_file`	共享文件（用户、组、域、任何人）
`list_permissions`	列出有权访问文件的人
`get_permission`	检查特定权限
`update_permission`	更改权限的访问级别
`delete_permission`	取消访问（取消共享）
`empty_trash`	永久删除所有被丢弃的文件
`get_about`	获取存储配额、用户信息、导出格式
`list_shared_drives`	列出共享驱动器
`get_shared_drive`	获取共享驱动器详细信息
`create_shared_drive`	创建新的共享驱动器
`update_shared_drive`	更新共享驱动器的名称或设置
`delete_shared_drive`	删除空的共享驱动器
`list_revisions`	列出文件版本历史记录
`get_revision`	获取特定文件修订的详细信息
`delete_revision`	删除特定的文件修订版
`list_changes`	跟踪自某个时间点以来Drive的变化

谷歌日历（26个工具）

工具	说明
`list_accounts`	列出已配置的帐户
`list_calendars`	列出所有可访问的日历
`get_calendar`	获取日历详细信息（名称、时区、描述）
`create_calendar`	创建新日历
`update_calendar`	更新日历的名称、描述或时区
`delete_calendar`	删除辅助日历
`get_calendar_list_entry`	获取详细的日历列表条目（颜色、通知、可见性）
`subscribe_calendar`	订阅公共或共享日历
`unsubscribe_calendar`	从列表中删除日历
`update_calendar_list_entry`	更新显示设置（名称覆盖、颜色、可见性）
`list_events`	列出时间范围内的事件
`get_event`	获取活动详细信息
`create_event`	创建新事件（带有可选的驱动器文件附件）
`update_event`	更新现有事件（带有可选的驱动器文件附件）
`delete_event`	删除事件
`respond_event`	回复邀请（接受/拒绝/暂定）
`quick_add_event`	用自然语言创建事件（例如“明天中午的午餐”）
`list_event_instances`	列出重复事件的发生情况
`move_event`	将事件移动到其他日历
`query_free_busy`	检查某个时间范围内用户/日历的可用性
`share_calendar`	共享日历（用户、组、域或公共）
`list_calendar_sharing`	日历的列表共享规则（ACL）
`get_acl_rule`	获取特定共享规则的详细信息
`update_acl_rule`	更新共享规则的角色
`delete_acl_rule`	删除共享规则（撤销访问权限）
`get_colors`	获取日历和活动的可用调色板

本地文件工具（有条件）

这些工具出现在 所有服务器 当 --allow-read-dir 或 --allow-write-dir 已设置：

工具	说明
`list_local_files`	列出允许的本地目录中的文件
`read_local_file`	从允许的本地目录读取文本文件（512 KB限制）

这 list_local_files 工具描述包括配置的目录路径和访问模式，因此LLM知道什么是可用的，而不会猜测。

多账户查询

所有只读工具支持 account="all" 在每个配置的帐户中展开查询：

search(account="all", query="from:boss subject:urgent")       # on gmail server
search(account="all", query="name contains 'report'")         # on drive server
list_events(account="all")                                     # on calendar server

配置

文件	目的
`<config-dir>/credentials.json`	来自Google Cloud控制台的OAuth客户端凭据
`<config-dir>/tokens.json`	存储的帐户令牌（由创建 `auth add`)

config目录使用平台本机位置（Linux： ~/.config/google-mcp，macOS： ~/Library/Application Support/google-mcp，Windows： %AppData%\google-mcp).覆盖 --config-dir.

许可证

麻省理工学院