AI导哈

谷歌工作空间MCP服务器

一个MCP（模型上下文协议）服务器，通过标准化工具接口为AI助手提供Gmail和Google日历的访问功能。

  • by Solarrixs
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Solarrixs/google-workspace-mcp

使用说明

谷歌工作区MCP服务器

MCP（模型上下文协议）服务器，通过标准化的工具界面让人工智能助手访问Gmail和谷歌日历。使用TypeScript构建。

特征

Gmail

  • 线程 --列出并阅读带有全文处理功能的电子邮件线程（引号删除、签名删除、HTML到文本转换）
  • 草稿 --使用线程回复支持创建、更新、列出和删除电子邮件草稿（仅草稿，从不发送）
  • 标签 --列出所有Gmail标签（系统+用户）

日历

  • 事件 --创建、列出、更新和删除日历事件，支持全天活动、与会者和地点

先决条件

  • Node.js 18+
  • Google Cloud项目 Gmail API 和 谷歌日历API 启用
  • OAuth 2.0客户端凭据（桌面应用程序类型）来自 谷歌云控制台

设置

1.安装依赖项

npm install

2.运行OAuth设置向导

npm run setup

这将：

  1. 提示您输入OAuth客户端ID和客户端密码
  2. 提示您 帐户别名 （例如，“工作”、“个人”）
  3. 打开浏览器窗口进行谷歌授权
  4. 在上启动本地回调服务器 http://localhost:3000/oauth2callback
  5. 将令牌保存到 ~/.config/google-workspace-mcp/tokens.json 多账户格式
  6. 验证Gmail和日历API的访问权限

跑 npm run setup 再次添加更多帐户。第一个帐户将成为默认帐户。

重定向URI：确保 http://localhost:3000/oauth2callback 在您的Google Cloud Console OAuth凭据中列为授权重定向URI。

没有刷新令牌？ 如果安装程序因未收到刷新令牌而失败，请在以下位置撤销应用程序访问权限https://myaccount.google.com/permissions并再次运行安装程序。

3.构建和运行

npm run build
npm start

与MCP客户端一起使用

添加到您的MCP客户端配置（Claude Desktop、Claude Code等）：

{
  "mcpServers": {
    "google-workspace": {
      "command": "node",
      "args": ["/absolute/path/to/google-workspace-mcp/dist/index.js"]
    }
  }
}

凭据从加载 ~/.config/google-workspace-mcp/tokens.json （由创建 npm run setup).环境变量(GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, GOOGLE_REFRESH_TOKEN)支持作为单帐户使用的后备方案，但 npm run setup 这是推荐的方法。

可用工具

所有工具都接受可选 account 用于选择使用哪个Google帐户的参数（例如。， account: "work").省略它以使用默认帐户。

账户管理

工具 说明
list_accounts 列出已配置的Google帐户和默认帐户。用于发现可用的帐户别名

Gmail

工具 说明
gmail_list_threads 列出带有可选搜索查询的线程(is:inbox, newer_than:14d, from:me等）、分页和最大结果
gmail_get_thread 阅读完整的线程内容——所有带有正文的消息，或 minimal 仅用于元数据的格式
gmail_create_draft 使用可选线程创建电子邮件草稿(thread_id, in_reply_to).支持/cc/bcc
gmail_update_draft 更新现有草稿——只提供要更改的字段
gmail_delete_draft 永久删除草稿
gmail_list_drafts 列出所有带有ID、主题和收件人的草稿
gmail_list_labels 列出所有Gmail标签（系统和用户，包括超人自动标签）
gmail_download_attachment 下载附件（通过 message_id + attachment_id 从 gmail_get_thread)到磁盘；默认为临时临时临时目录（24小时后自动修剪），返回本地路径。通过 save_dir 保持它（例如。 ~/Downloads)

日历

工具 说明
calendar_list_events 按时间范围列出事件（默认值：现在到7天）。验证 time_min <= time_max.支持自定义 calendar_id
calendar_create_event 创建一个事件，包括摘要、开始/结束、与会者、位置、描述
calendar_update_event 更新事件——只发送更改的字段（PATCH）。必须至少提供一个字段
calendar_delete_event 删除事件

OAuth范围

范围 目的
gmail.readonly 阅读帖子、消息、标签
gmail.compose 创建和管理草稿
gmail.labels 列出标签
calendar 完整日历读/写

发展

npm run build          # Compile TypeScript (tsc → dist/)
npm test               # Run all tests (vitest)
npx vitest run tests/drafts.test.ts   # Run a single test file

项目结构

src/
├── index.ts              # MCP server — 13 tools with account param, transport
├── auth.ts               # Multi-account OAuth2 factory, token migration, account resolution
├── utils.ts              # compact() utility
├── gmail/
│   ├── threads.ts        # Thread list/get with text processing pipeline
│   ├── drafts.ts         # Draft CRUD, RFC 2822 email building
│   └── labels.ts         # Label listing
└── calendar/
    └── events.ts         # Calendar event CRUD

tests/                    # Vitest — mock-based, no real API calls
scripts/
└── setup-oauth.ts        # Interactive OAuth setup wizard
specs/                    # Planned feature specs (see specs/email-watcher.md)

看 CLAUDE.md 详细的架构文档和 INDEX.md 逐个文件引用。

许可证

麻省理工学院

相关 MCP