Google 工作空间 MCP 服务器
让您的 AI 代理真实访问 Google 工作空间 ——Gmail, Calendar, Drive, Docs, Sheets, Tasks, Meet and Contacts——来自一个MCP服务器,横跨尽可能多的账户.
搜索您的邮件,检查您的日历,写一个医生,提交一个任务——在对话中,作为你自己.
安装
首先,你必须 谷歌 OAuth 证书 - 每一条道路的共同先决条件:
- 转到 控制台.cloud.google.com/apis/证书
- 创建一个 OAuth 2.0 客户端标识,应用程序类型 桌面应用程序
- 启用您想要的 API( 邮件、 日历、 驱动器、 工作表、 文件、 任务、 满足—— 和) 人民协会 对于联系人,Google在控制台上称之为联系人)
- 留着 客户身份 财务报告和审定财务报表 客户端机密 方便,你会贴在下面
然后选择与工作方式相匹配的路径. 三个都运行同一服务器.
节点22.12或更新. (节点18和20均为报废. )
* * * * * * * * 克洛德·桌面——一击 .mcpb 安装( 建议)
下载 google-workspace-mcp.mcpb 从 最新发布,则 拖到 Claude 桌面窗口,或双击.
Claude 桌面打开安装对话框, 包含三个字段:
| 外地 | |
|---|---|
| Google OAuth 客户端标识 | 所需 -- -- 从上文步骤 |
| Google OAuth 客户端机密 | 所需 -- -- 从上文步骤 |
| 工作空间目录 | 可选的——其中附件,下载和输出为地. 默认为 ~/.local/share/google-workspace-mcp/workspace/。给它一个专用文件夹——而不是您的家、文档、桌面或Google Drive文件夹. |
粘贴,击出"保存",完成. 没有JSON可以编辑,没有节点可以安装,没有路径可以得到正确的——捆绑携带服务器和每一个依赖.
每个平台都有一个包 ——macOS(英特尔和苹果硅),Linux(x64和ARM64),和Windows. 没有什么可以选择的:服务器是纯JavaScript的,所以没有特定平台的有效载荷可以选择在两者之间.
跨平台注释 :
.mcpb文件通过克洛德桌面的捆绑处理器安装. 如果双击没有触发克洛德在您的系统中,则将文件拖到克洛德桌面窗口上,或者右击 → " Open with..." 并选择克洛德桌面(然后,如果您的OS主动提出"永远用"打开). 行为不一:macOS通常自动关联,Windows可能需要一次性关联,Linux因桌面环境而异.
Claude 代码——一个命令
claude mcp add google-workspace \
-e GOOGLE_CLIENT_ID=your-client-id \
-e GOOGLE_CLIENT_SECRET=your-client-secret \
-- npx -y @aaronsb/google-workspace-mcp
就是这样——没有文件可以编辑. 校验 /mcp。 。 。 .
其他MCP客户
在客户端的 MCP 配置文件上添加一个条目( 用于 Claude Desktop 手动操作, 即 claude_desktop_config.json克劳德・科德, .mcp.json:
{
"mcpServers": {
"google-workspace": {
"command": "npx",
"args": ["-y", "@aaronsb/google-workspace-mcp"],
"env": {
"GOOGLE_CLIENT_ID": "your-client-id",
"GOOGLE_CLIENT_SECRET": "your-client-secret"
}
}
}
}
或者在全球安装,直接指向二进制:
npm install -g @aaronsb/google-workspace-mcp
如何融为一体
flowchart LR
human["🧑 You<br>ask in plain language"]
agent["🤖 Your AI agent<br>Claude Desktop, Claude Code…"]
server["⚙️ This MCP server<br>picks the right account,<br>builds the real request"]
keys[("🔑 Your accounts<br>OAuth tokens, kept<br>on your own machine")]
google["☁️ Google<br>Gmail · Calendar · Drive · Docs<br>Sheets · Tasks · Meet · Contacts"]
human -->|"“what's on my calendar?”"| agent
agent -->|"tool call"| server
server <-->|"which account?"| keys
server -->|"real API call, as you"| google
google -->|"your data"| server
server -->|"shaped for an agent<br>+ what to do next"| agent
agent -->|"an answer"| human
classDef person fill:#475569,color:#ffffff,stroke:#94a3b8
classDef robot fill:#2d7d9a,color:#ffffff,stroke:#4a5568
classDef ours fill:#7c3aed,color:#ffffff,stroke:#8b5cf6
classDef secrets fill:#2d8e5e,color:#ffffff,stroke:#4a5568
classDef external fill:#f6821f,color:#1a1a1a,stroke:#d97706
class human person
class agent robot
class server ours
class keys secrets
class google external
你的证书从不离开你的机器. 服务器在您自己的磁盘上持有每个账户的 OAuth 令牌,并呼叫 Google 和你一样 ——没有中间人服务,没有说明我们的服务,没有什么可以报名的. 添加您喜欢的账户( 个人账户和工作账户, 并列账户) ; 服务器将每个请求运行到右侧 .
它能做些什么
8个谷歌服务的12个工具,加上多账户处理,每个账户只读访问,批量执行,内容编写,和一个文件沙盒.
| 工具 | 它会做什么 |
|---|---|
manage_email | Gmail — 搜索, 读取( 平面或 sanited HTML), 发送, 回复/ 回复全部, 转发, 分类, 垃圾, 草稿( 列表/ 删除), 标签, 线程, 附件 |
manage_calendar | 日历——列表,议程,获取,创建,快速Add(自然语言),更新,删除,日历,freebusy |
manage_drive | 驱动器 — 搜索、 获取、 上传、 下载、 复制、 重命名/ 移动、 删除、 导出、 权限、 评论、 查看图像 |
manage_sheets | 工作表 — 读取/ 写入范围( row- 数字输出) , 附加, 清除, 管理标签, 复制/ 复制/ 重命名 |
manage_docs | Docs — 获取、创建、附加、插入文本、查找和替换 |
manage_tasks | 任务——列表/创建/更新/完成任务和任务列表 |
manage_meet | 开会——创造和配置会议空间,看现在是谁在打电话,浏览过去的会议、与会者、记录稿、录音、智能笔记 |
manage_contacts | 联系人 – 在您保存的联系人中查找人, 您只对应的地址以及您的组织目录; 创建、 更新和删除联系人 |
manage_accounts | 多账户周期——增加账户,管理证书和范围 |
manage_scratchpad | 编译/编辑多行内容(线-或 JSON- path- addressed), 附加文件, 发送到任何目标; JSON 模式活同步到 Docs / 工作表 |
manage_workspace | 工作空间沙盒中的文件操作( 附件、下载、导出交换点) |
bulk_operations | 在一个呼叫中做许多事情——按顺序将不同的操作与 $N.field 引用,或在一个Google请求中对许多资源应用一个操作(queue_operations 仍然作为别名工作) |
每一个反应都带有 下一步 引导,所以代理总是知道 下一步可以做什么.
一个问,许多步骤
有用的部分不是任何单一的操作,而是你的经纪人可以 把它们串在一起。 。 。 .
你问一件事。 代理商认为,它需要四个API呼叫, 顺序,每个喂下一个:
sequenceDiagram
autonumber
participant H as 🧑 You
participant A as 🤖 Your agent
participant S as ⚙️ MCP server
participant G as ☁️ Google
H->>A: "file the invoice from Acme<br>and remind me to pay it Friday"
A->>S: find the email
S->>G: search Gmail
G-->>S: the message
S-->>A: found it — and here's what you can do next
A->>S: save the attachment
S->>G: download it
A->>S: put it in Drive
S->>G: upload
A->>S: create a task, due Friday
S->>G: Google Tasks
A-->>H: Done. Invoice filed, task set for Friday.
二事使此相能通达. 每一次回复都告诉特工 接下来它能做什么所以,这不是猜测 在下一步。 还有 bulk_operations 让它运行整个链 一通电话,将每个结果输入下一个结果——所以"找到发票,归档,提醒我"是一次来回旅行而不是四次.
当工作是 同样的 使用Google的一次请求
bulk_operations { mode: 'batch', tool: 'manage_email', operation: 'trash',
items: ['msg1', 'msg2', 'msg3', … ] }
两百条信息在一次往返中被浪费,而不是200条. 这在目的上是狭义的——它只在Google为其发布一种方法的情况下才有效,即今天的联系人(创建,更新,删除,获取)和Gmail(垃圾,标签更改). 在其它任何地方询问,答案则指定可以操作的操作名称,并将您指向连续模式,该模式随处可见.
问少了什么
此服务器曝光 95次业务达到79个 257方法 Google出版这8个API. 它是一个专有的子集: 特工必须 选择 在这些方法中,它必须权衡的每一个方法都是可以错误选择的。 拥有257个操作的工具的能力不比拥有95个的更强——它更难正确使用.
但判决是没有你的.
每个方法都被列出——它做什么,我们是否揭露,以及 请求 链接打开预填出的问题。 描述是Google自己的,被引用的逐字记录,页面由客户端构建的相同规格生成,因此无法从现实中漂移.
该页还列出了 3个完整的API 此服务器尚未触摸 聊天、幻灯片和表格,原因相同: 非目标 是一个决定,而不是自然的事实.
不错的要求 命名任务,而不是方法数字 :
"我要经纪人自动将收到的发票存入文件夹"
这一点可以评估。 它可能证明一个已有的操作已经这样做了,或者正确的答案是一个不同于你找到的方法. "发表 users.settings.filters.create" (中文(简体) ) 这是一种结论,而不是一种案例——首先解决问题,然后让方法遵循.
为什么是Apache 2.0,而不是打开核心
一切都在这里. 没有付费等级,没有"企业"的建设,没有特性可以留待日后出售. 你安装的是存在的东西.
开放核心通过保持好部分后退. 自由的东西是铅磁铁,一旦你的使用变得严肃,你就会发现你需要生命的操作在许可证后面. 这个模型会特别烂 这里这是一块管道 你和 您自己的数据,使用 您自己的谷歌证书运行中 自己的机器任何关于这种安排的东西都不应该有一个支付墙的中间,也不需要一个供应商.
Apache 2.0 (英语) 而不是麻省理工学院,原因有两个:
- 明确授予专利权. 贡献者将他们的专利要求连同他们的密码一起许可,所以使用这个方法以后不能成为专利问题. 麻省理工学院对专利保持沉默,这意味着这个问题只是没有得到答复,而不是得到解决.
- 工作上收养是安全的. Apache 2.0 基本上在每个公司的许可名单上。 把它叉出,卖出,装入商业产品里去——你什么都不欠任何人,你不需要问.
一项义务是归责:保持通知(NOTICE, (中文(简体) ), LICENSE与代码。 就是这样.
通过v3.0.0,这个项目得到了麻省理工学院的许可,历史被保存下来而不是被抹去——麻省理工学院时代的捐款保持了最初的通知 LICENSE-MIT,并且他们的作者记入 NOTICE阿帕奇2.0拿回了麻省理工学院不允许的.
使用量
添加账户( 为 OAuth 打开浏览器) :
manage_accounts { "operation": "authenticate" }
然后使用您账户电子邮件的任何工具 :
manage_email { "operation": "triage", "email": "[email protected]" }
manage_calendar { "operation": "agenda", "email": "[email protected]" }
manage_drive { "operation": "search", "email": "[email protected]", "query": "quarterly report" }
提供账户只读访问
有些账户永远不应写入。 同意时要求少一点 符号本身 无法发送、编辑或删除 —— 这不是在宽符号上分层的规则 :
manage_accounts { "operation": "scopes", "email": "[email protected]",
"services": "gmail,drive,contacts", "access": "read" }
Google被要求每个范围只读的变体,所以在同意屏幕上勾选每个框仍然产生只读的符号. manage_accounts status 报告每个账户的实际持有情况.
在请求离开之前,只读账户的写作被拒绝,并附有账户、操作和回路:
'create' needs write access to contacts. Account [email protected] was authorized
read-only for contacts. Re-authorize with manage_accounts {operation:'scopes',
email:'[email protected]', services:'contacts', access:'readwrite'}, or use an
account that already has it.
如果一个服务没有只读范围, 你被告知哪些,他们还能做什么 在此之前 浏览器打开.
多步骤工作流程
带结果参考的链路操作——一个步骤的输出为下一个步骤提供了信息:
{
"operations": [
{ "tool": "manage_email", "args": { "operation": "search", "email": "[email protected]", "query": "from:boss subject:review" }},
{ "tool": "manage_email", "args": { "operation": "read", "email": "[email protected]", "messageId": "$0.messageId" }}
]
}
一个行动,很多事情
Google发布方法时
{
"mode": "batch",
"tool": "manage_contacts",
"operation": "delete",
"email": "[email protected]",
"items": ["people/c1", "people/c2", "people/c3"]
}
整个批量共享的任何东西都是在顶层; items 只携带不同的东西——光是身份就足够了.
你的数据所在的地方
遵循 XDG 基础目录规格 :
| 数据 | 地点 |
|---|---|
| 账户登记册 | ~/.config/google-workspace-mcp/accounts.json |
| 全权证书 | ~/.local/share/google-workspace-mcp/credentials/ |
| 工作空间( 文件交换) | ~/.local/share/google-workspace-mcp/workspace/ |
证书是每个账户的文件,持有标准的OAuth令牌. 项目目录中不存储任何秘密 .
在车盖下
你不需要这些东西来使用服务器. 但是,如果你好奇, 或者你想增加一个操作:
服务器构建其 Google API 客户端 从谷歌自己的机器可读API规格. 无一是用手来转写,所以表面无法从现实中漂移出,而添加一个操作是YAML编辑而不是代码更改.
- 如何运作 ——建设时间/运行时间分拆,描述器,工厂
- API 覆盖率 ——什么暴露了,什么没有,如何要求更多
- 完整的 API 表面 ——谷歌发布的每一种方法,加上我们尚未针对的三个API
- 结构决定 —— ADRs,包括为什么这个服务器直接拥有其Google客户端
许可证
Apache 许可证 2.0 看到了吗 为什么是Apache 2.0 见上文.