gws-admin-mcp

gws-admin-mcp

一个本地 Model Context Protocol（MCP）服务，为你的 AI Agent （Cursor、Claude Desktop 或任何 MCP 客户端）提供一个安全的 Google Workspace 管理控制台。它通过一个启用了全网域委派的服务账号调用 Admin SDK（Directory、Reports、Groups Settings），因此 Agent 可以回答“哪些用户已 90 天未登录？”或“谁属于 Finance 群组？”等问题——并且只有在你明确允许时，才会进行更改。

MCP client ──stdio──► gws-admin-mcp ──service account JWT (impersonates an admin)──► admin.googleapis.com / groupssettings.googleapis.com

完全在你的计算机上运行。没有第三方服务，没有遥测；除 Google API 调用本身外，数据不会离开你的笔记本电脑。

安全模型

此服务假设驱动它的 Agent 可能会出错。安全保障分为三层：

1. 默认只读。 默认情况下仅注册 17 个读取工具——写入工具并非通过运行时检查隐藏，而是根本不存在于工具列表中，因此 Agent 无法调用它们。需要使用 --allow-write（或 GWS_ADMIN_ALLOW_WRITE=1）启动服务，才能执行更改。
2. 破坏性调用需要确认。 即使启用了写入功能，除非调用中包含 "confirm": true，否则也会拒绝不可逆操作——users_delete、groups_delete、 orgunits_delete、role_assignment_delete、移动设备清除操作，以及 ChromeOS 取消配置操作。Agent 必须再次明确表示要执行破坏性操作。
3. 审计日志。 每次工具调用都会以 JSON 行的形式追加到 ~/.config/gws-admin-mcp/audit.log（权限模式为 600），密码和机密信息会被编辑隐藏。如有需要，可通过 GWS_ADMIN_AUDIT=0 禁用。

建议的使用方式：让只读实例持续运行，仅在需要进行更改的时段启动第二个启用写入功能的实例。

工具（共 40 个；只读模式下有 17 个）

区域	只读工具	写入工具（需要 --allow-write）
用户	users_list、users_get	users_create、users_update、users_suspend、users_unsuspend、users_reset_password、users_make_admin、users_move_ou、users_delete*
群组	groups_list、groups_get、groups_list_members	groups_create、groups_update、groups_delete*、groups_add_member、groups_remove_member、groups_update_member
组织部门	orgunits_list、orgunits_get	orgunits_create、orgunits_update、orgunits_delete*
角色	roles_list、role_assignments_list	role_assignment_create、role_assignment_delete*
网域 / 客户	domains_list、customer_get	—
设备	devices_list_mobile、devices_list_chromeos	devices_action_mobile、devices_action_chromeos、devices_move_chromeos
报告	reports_activities（审计日志）、reports_usage_user、reports_usage_customer	—
群组设置	groupsettings_get	groupsettings_update

* 破坏性操作——调用时还必须包含 "confirm": true （设备工具仅对清除/取消配置操作有此要求）。

列表工具会自动翻页，最多达到 maxResults 上限；users_list 支持完整的 Admin SDK 搜索语法（orgUnitPath='/Sales'、isAdmin=true、 email:jdoe*，等等）。

要求

• Node.js >= 20
• 拥有 Google Workspace 网域的超级管理员权限（用于授予全网域委派）
• Google Cloud 项目（免费——Admin SDK 不产生使用费用）

Google Cloud 设置

你需要一个服务账号，服务会使用它的密钥来模拟 Workspace 超级管理员。有两种方式：

方式 A — 脚本设置（需要 gcloud）

gcloud auth login [email protected]
scripts/setup-service-account.sh [email protected] your-project-id

脚本会创建或复用项目，启用 Admin SDK 和 Groups Settings API，创建服务账号，将密钥和配置写入 ~/.config/gws-admin-mcp/，并输出客户端 ID 和范围字符串，供最后的手动步骤使用（下方的第 5 步——Google 未提供用于该步骤的 API）。

路径 B — 手动配置（Cloud 控制台）

1. 在 console.cloud.google.com 创建项目 （也可以复用专用于管理工具的项目）。
2. 启用 API：Admin SDK API 和 Groups Settings API （API 和服务 → 库）。
3. 创建服务账号（IAM 和管理 → 服务账号 → 创建）。 无需分配项目级 IAM 角色——它的全部权限都来自后续步骤中的 委托授权。
4. 为其创建 JSON 密钥（密钥标签页 → 添加密钥 → JSON），并将其保存为 ~/.config/gws-admin-mcp/service-account.json，然后运行 chmod 600。
5. 授予全网域委托权限——这是容易遗漏的一步：
   • 复制服务账号的 OAuth 2 客户端 ID（一个长数字，显示在 服务账号详情页上）。
   • 在管理控制台（admin.google.com）中： 安全性 → 访问和数据控制 → API 控制 → 全网域委托 → 添加新内容。
   • 粘贴客户端 ID，并将以下完整范围列表粘贴为一行、以逗号分隔的文本：

https://www.googleapis.com/auth/admin.directory.user,https://www.googleapis.com/auth/admin.directory.group,https://www.googleapis.com/auth/admin.directory.group.member,https://www.googleapis.com/auth/admin.directory.orgunit,https://www.googleapis.com/auth/admin.directory.rolemanagement,https://www.googleapis.com/auth/admin.directory.domain.readonly,https://www.googleapis.com/auth/admin.directory.customer.readonly,https://www.googleapis.com/auth/admin.directory.device.mobile,https://www.googleapis.com/auth/admin.directory.device.chromeos,https://www.googleapis.com/auth/admin.reports.audit.readonly,https://www.googleapis.com/auth/admin.reports.usage.readonly,https://www.googleapis.com/auth/apps.groups.settings

6. 指定服务应模拟的管理员。 创建 ~/.config/gws-admin-mcp/config.json：

{
  "delegatedAdmin": "[email protected]",
  "customerId": "my_customer"
}

delegatedAdmin 必须是网域的超级管理员。my_customer 会解析为该管理员所属的组织。

环境变量会覆盖配置文件：GOOGLE_SA_KEY（密钥路径）、 DELEGATED_ADMIN、CUSTOMER_ID、GWS_ADMIN_CONFIG_DIR（备用配置 目录）。请参阅 .env.example。

构建和验证

npm install
npm run build
node dist/cli.js doctor

doctor 会检查密钥、生成委托令牌，并对用户、网域、角色和 审计报告 API 执行示例读取。这四项都应显示 PASS。然后可以选择运行：

npm run smoke   # spawns the real server over stdio, checks tool registration + live reads

MCP 客户端配置

Cursor（~/.cursor/mcp.json）

只读——推荐的默认配置：

{
  "mcpServers": {
    "gws-admin": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gws-admin-mcp/dist/cli.js", "serve"]
    }
  }
}

启用写入（请谨慎使用，最好作为第二个条目，需要时再切换启用）：

{
  "mcpServers": {
    "gws-admin-write": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gws-admin-mcp/dist/cli.js", "serve", "--allow-write"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）

macOS：~/Library/Application Support/Claude/claude_desktop_config.json · Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "gws-admin": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/gws-admin-mcp/dist/cli.js", "serve"]
    }
  }
}

编辑后重启客户端。你应会看到 gws-admin 服务，其中包含 17 个工具（只读）或 40 个工具（启用写入）。

故障排查

症状	原因 / 解决方法
生成令牌时出现 unauthorized_client	缺少全网域委托授权、使用了错误的客户端 ID，或范围列表未涵盖服务请求的所有范围。请针对服务账号的 OAuth2 客户端 ID，重新粘贴上方的完整范围字符串。授权可能需要几分钟才能生效。
Service-account key not found at ...	将 JSON 密钥放在 ~/.config/gws-admin-mcp/service-account.json，或将 GOOGLE_SA_KEY 设置为其路径。
DELEGATED_ADMIN ... is not set	在 config.json 中添加 delegatedAdmin，或设置 DELEGATED_ADMIN 环境变量。
403 Not Authorized to access this resource/api	被模拟的用户不是超级管理员，或 Cloud 项目中未启用 Admin SDK API。
Groups Settings 调用返回 404	项目中未启用 Groups Settings API（它与 Admin SDK 是分开的）。
客户端中未显示写入工具	这是预期行为——使用 --allow-write 或 GWS_ADMIN_ALLOW_WRITE=1 启动服务。
删除/清除调用返回 Refused: ... destructive/irreversible	这是预期行为——使用 "confirm": true 重新发起调用。
客户端显示服务启动失败	在终端中运行 node dist/cli.js doctor；它会显示具体失败的检查项。另请确认 MCP 配置中的 args 路径是绝对路径。

安全说明

• 服务帐号密钥可冒充拥有整个组织权限的超级管理员。 请像对待域管理员密码一样保护 service-account.json：不要将其提交到 git（本仓库的 .gitignore 已排除密钥文件、.env 和 config.json），将权限设为 chmod 600，并定期轮换。
• 建议为此服务帐号使用专用的 Cloud 项目，以便轻松审计和撤销密钥。
• 请让永久实例保持只读。只有在确实要更改内容时，才在单独的实例中 启用写入，并在之后将其关闭。

许可与购买

本仓库提供源代码，但并非开源：代码公开，因此你可以在信任它处理超级管理员 凭据之前，阅读并审查每一行代码，但使用它需要许可证。

• 购买许可证（$34）： antchoutine.gumroad.com/l/gws-admin-mcp — 永久有效，包含完整的可写入版本和更新。
• **免费试用：**只读版本（17 个工具，不含任何修改代码）可在 npm 上获取：gws-admin-mcp。

请参阅 LICENSE 了解完整条款（不得再分发，也不得将其作为托管服务提供）。