mariana-google-mcp

一个自定义的 MCP (Model Context Protocol) 服务器，让 Claude Code 可以访问 Gmail、Google 日历和 Google 联系人，并采用安全优先的默认设置。

设计理念

此服务器专为希望 AI 协助管理其 Google 工作区且不希望发生意外损坏的用户而构建：

不发送电子邮件。 您可以起草邮件，但发送需要手动在 Gmail 中操作。
不删除任何内容。 Gmail 使用“To Be Deleted”（待删除）标签（软删除）。日历会在活动标题前加上“DELETE - ”。您需要在 Google UI 中进行审查和确认。
记录每一次变更。 一个仅追加的 JSONL 操作日志会记录每一次写入操作，包括时间戳、工具名称、账户和摘要。
多账户支持。 使用别名管理个人和工作账户。

设置

1. Google Cloud 项目

前往 Google Cloud Console
创建一个新项目（或使用现有项目）
启用以下 API：
- Gmail API
- Google Calendar API
- People API（用于联系人）
创建 OAuth 2.0 凭据：
- 应用程序类型：桌面应用
- 下载客户端 ID 和客户端密钥

2. 安装与构建

git clone https://github.com/marianasmall/mariana-google-mcp.git
cd mariana-google-mcp
npm install
npm run build

3. 添加到 Claude Code

将此内容添加到 ~/.claude.json 中的 mcpServers 下：

{
  "mcpServers": {
    "mariana-google-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mariana-google-mcp/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

将 /path/to/ 替换为您克隆项目的实际路径，并填入您的 OAuth 凭据。

4. 身份验证

重启 Claude Code 后，运行 google_auth 工具。它将打开一个浏览器窗口进行 OAuth 授权。授权后，您的令牌将存储在本地并自动刷新。

可用工具 (19)

身份验证与状态

工具	描述
`google_auth`	通过 OAuth 浏览器流程验证 Google 账户
`google_status`	检查所有已配置账户的连接健康状况

Gmail (9 个工具)

工具	描述
`gmail_search`	使用 Gmail 查询语法搜索邮件
`gmail_read`	通过 ID 读取特定邮件（完整内容）
`gmail_list_labels`	列出所有 Gmail 标签/文件夹
`gmail_draft`	创建邮件草稿（不会发送）
`gmail_create_label`	创建新标签（支持使用 `/` 进行嵌套）
`gmail_apply_label`	将标签应用于一封或多封邮件
`gmail_remove_label`	从一封或多封邮件中移除标签
`gmail_create_filter`	创建过滤规则（匹配条件 → 操作）
`gmail_move_to_delete`	软删除：将邮件移动到“To Be Deleted”标签

日历 (6 个工具)

工具	描述
`calendar_list`	列出即将到来的日历活动
`calendar_search`	按关键字搜索活动
`calendar_get`	获取特定活动的详细信息
`calendar_create`	创建活动（默认不会发送邀请）
`calendar_update`	修改现有活动（默认不会通知参与者）
`calendar_flag_delete`	软删除：在活动标题前加上“DELETE - ”
`calendar_availability`	检查日期范围内的空闲/忙碌状态

联系人 (2 个工具)

工具	描述
`contacts_search`	按姓名、电子邮件或电话搜索联系人
`contacts_list`	列出联系人，可选择按组过滤

多账户支持

您可以验证多个 Google 账户并使用友好名称：

google_auth account_name: "primary"
google_auth account_name: "newsletters"
google_auth account_name: "work"

大多数工具接受可选的 account 参数。如果省略，则使用默认账户。使用 google_status 查看所有已配置的账户及其健康状况。

配置文件

所有配置均存储在 ~/.config/mariana-google-mcp/ 中：

文件	用途
`config.json`	账户注册表（名称、电子邮件哈希、默认值）
`tokens/<hash>.json`	每个账户的 OAuth 令牌（自动刷新）
`actions.jsonl`	所有变更的仅追加日志

令牌按电子邮件哈希存储，而非明文电子邮件，以增加一层间接性。

操作日志

每一次写入操作（草稿、日历创建/更新、软删除）都会以以下格式记录到 ~/.config/mariana-google-mcp/actions.jsonl：

{"timestamp":"2026-04-03T10:30:00.000Z","tool":"gmail_draft","account":"primary","summary":"Draft created: subject='Meeting follow-up'"}

该日志仅可追加，服务器绝不会对其进行修改。您可以随时查看它以审计 Claude 的操作。

分叉与使用

要将其用于您自己的 Google 账户：

分叉此仓库
创建您自己的 Google Cloud 项目和 OAuth 凭据（见上文“设置”）
构建并将您的 Claude Code 配置指向您分叉仓库的 dist/index.js
运行 google_auth 进行验证

无需更改代码 — 所有账户特定的数据都存储在配置文件和环境变量中。

技术栈

TypeScript
@modelcontextprotocol/sdk — MCP 协议实现
googleapis — Google API 客户端
google-auth-library — OAuth2 令牌管理
zod — 输入验证

许可证

MIT

Mariana Google MCP