# @a1-x-tech/mcp-google-auth 中文文档

规范地址：https://npmcn.com/package/%40a1-x-tech/mcp-google-auth/

版本：0\.1\.2
npm 元数据更新时间：2026-11-04T20:13:41.305Z
中文译文更新时间：2026-11-06T17:30:09.286Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40a1-x-tech/mcp-google-auth
原文对照：https://npmcn.com/package/%40a1-x-tech/mcp-google-auth/?lang=original
项目主页：https://github.com/A1-x-Tech/mcp-google-auth#readme
源码仓库：https://github.com/A1-x-Tech/mcp-google-auth

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：92.1 kB，19 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：1 个
- peer 依赖：@modelcontextprotocol/sdk ^1\.29\.0
- 首次发布：2026-09-20T13:40:53.939Z
- 最新版本发布：2026-11-04T20:13:41.103Z
- 近 30 天下载量：2580（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：3（近 12 个月 3 个）

## 中文简介

Mcp-google- \* MCP 服务器行的可再用 Google OAuth 登入: 聊天登录工具(loopback + PKCE)和每个请求的TokenProvider.

## 安装

```sh
npm install @a1-x-tech/mcp-google-auth
```

也可以使用：`pnpm add @a1-x-tech/mcp-google-auth`、`yarn add @a1-x-tech/mcp-google-auth`、`bun add @a1-x-tech/mcp-google-auth`

## README

# @a1-x-tech/mcp-google-auth (英语)

可重用 Google OAuth 登录 `mcp-google-*` MCP服务器行. 一个 软件包给予每个服务器 Yandex 线的聊天登录——适应 谷歌的规则:a **打开回放收听器 `127.0.0.1` + 常设专家委员会(S256)** 改为 死亡的OOB流,一个 **用户拥有的桌面 OAuth 客户端** (个人使用) 豁免——无核查、无小武器问题协调行动)和a `set_client` 路径 `client_secret` 从不通过聊天.

这是一个 **图书馆**,而不是服务器: 它在您身上注册了六个 MCP 工具 `McpServer` 手拿回来 `TokenProvider` 您的 API 客户端每个请求都呼叫 .

## 使用量

```ts
import { registerGoogleAuth, unconfiguredPrefix } from "@a1-x-tech/mcp-google-auth";

const options = {
  serverName: "calendar",                 // → ~/.config/mcp-google-calendar/credentials.json
  envPrefix: "GOOGLE_CALENDAR",           // → GOOGLE_CALENDAR_REFRESH_TOKEN, …
  scopes: ["https://www.googleapis.com/auth/calendar.events"],
  // verifyIdentity?: async (accessToken) => ({ email }),  // default: OIDC userinfo
  // defaultClient?: { clientId, clientSecret? },           // built-in A1 client slot
  // finishWaitMs?: 20_000,                                  // finish_login wait for the callback
  // fail?: (err) => CallToolResult,                       // your error renderer (telemetry tag); default `Error: <message>`
};

const provider = registerGoogleAuth(server, options);

// In your API client, per request:
const token = await provider.getAccessToken();
// On a 401 from the API — one re-mint + replay:
const fresh = await provider.getAccessToken(true);
// Before a tool that needs a specific scope (partial grants are stored, not rejected):
provider.assertScopes(["https://www.googleapis.com/auth/calendar.events"]);

// At startup, when provider.hasToken() is false, prepend to the initialize instructions:
const instructions = unconfiguredPrefix(options) + REGULAR_BRIEFING;
```

该部分总是添加 `openid` + 键 `userinfo.email` 对(非敏感) `scopes` - 就是这样 `finish_login` 连API的账户都命名 一个身份电话.

## 注册工具

| 工具 | 提示 | 目的 |
| --- | --- | --- |
| `auth_status` | 只读 | 连接状态, 令牌源, 过期, 授予/ 丢失范围, 路径 。 没有网络, 输出中没有符号 . |
| `setup_instructions` | 只读 | GCP向导核对表(项目-API-同意屏幕-) **发布应用** – 桌面客户端 – 下载 JSON. 客户端已经存在时缩短 . |
| `set_client` | 写入 | 读取已下载 `client_secret_*.json` 以 **路径**类型 `installed`在共享中存储 `client.json` (0600) (中文(简体) ). 秘密从来不进入聊天. |
| `start_login` | **写入, 故意不只读** | 薄荷 PKCE + `state`,绑定一个一发收听器 `127.0.0.1` (随机端口或 `<PREFIX>_OAUTH_PORT`),返回时 `authorizeUrl` + 键 `nextStep`。不打开浏览器。 只读的提示会让快速注射静静地启动OAuth流. |
| `finish_login` | 写入 | 等待浏览器回调最多 20 s , 等待本地代码交换, 解剖保存符号, 验证身份( 服务器回调或用户信息), 报告 `accountEmail`, (中文(简体) ), `grantedScopes`, (中文(简体) ), `missingScopes`, (中文(简体) ), `previousAccountEmail` 账户变动. |
| `logout` | 破坏性 | 已撤销 `oauth2.googleapis.com/revoke`,删除文件、报表 `envTokenStillSet`。 。 。 . |

## 证书来源

**OAuth 客户端** (由全行分摊),优先权顺序:

1.  `<PREFIX>_CLIENT_ID` 编号 : `<PREFIX>_CLIENT_SECRET` (env 覆盖,例如 CI)
2.  `~/.config/mcp-google-auth/client.json` ——编著 `set_client`
3.  `options.defaultClient` ——已核实的A1客户端的内置槽

代码交换先运行 **无** `client_secret`; 如果 Google 回答 "客户 机密缺失",它用这个秘密重复 当一个人在档案中, 否则失败 `set_client` 建议.

**键** (每个服务器),优先排序 :

1.  `<PREFIX>_REFRESH_TOKEN` (+客户端)——以内存计价,从不写入磁盘; `<PREFIX>_ACCESS_TOKEN` 作为静态测试的替代品
2.  `~/.config/mcp-google-<serverName>/credentials.json` ——编著 `finish_login`, (中文(简体) ), **每次通话都要重读** (会中登录不需要重启)

路径荣誉 `$XDG_CONFIG_HOME`; 在Windows上,基础是 `%APPDATA%` (概况) ACLs 取代 0600/0700模式, 重命名反病毒重试 `EPERM`) (中文(简体) ). 写作 是原子 (temp 文件 + 重命名);一个已损坏的文件读取为"没有连接".

刷新: 60 s 回旋余地, 同时刷新去复, 旋转 `refresh_token` 立即坚持下去.

## 安全变化剂(每个都由测试所支撑)

-   没有工具输出或错误 `access_token` 编号 : `refresh_token` 编号 : `client_secret` 编号 : `id_token` (测试笔录上的sentinel grep).
-   PKCE核查员从不离开程序; `state` 精确比较 听者绑定 `127.0.0.1` 仅是一发,待登录者死亡 十分钟后 成功的一页是静止的——没有反射,没有外部的 资源.
-   缺少证书 `AuthRequiredError` **在此之前** 任何获取 信件名称`start_login`, env变量).
-   OAuth 失败映射到可采取行动的建议( E)`redirect_uri_mismatch`, (中文(简体) ), `access_denied`, (中文(简体) ), `accessNotConfigured`, (中文(简体) ), `invalid_scope`, (中文(简体) ), `invalid_grant`, (中文(简体) ), `invalid_client`, (中文(简体) ), `admin_policy_enforced`) (中文(简体) ).
-   部分同意赠款被储存和报告,从未被拒绝;账户 更改取消旧的刷新符牌和上一个名称 账户.

## 发展

```bash
npm install
npm run typecheck   # types for src + tests
npm test            # node:test, no external network (loopback only)
npm run build       # emit dist/
```

`@modelcontextprotocol/sdk` 是一个 **同伴依赖** ——主机服务器拥有 sDK 实例; 只 `zod` 作为运行时间的依赖.

## 许可证

麻省理工学院

## 常见问题

### @a1-x-tech/mcp-google-auth 是什么？

Mcp-google- \* MCP 服务器行的可再用 Google OAuth 登入: 聊天登录工具\(loopback \+ PKCE\)和每个请求的TokenProvider\.

### 如何安装 @a1-x-tech/mcp-google-auth？

在项目目录运行 npm install @a1-x-tech/mcp-google-auth，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@modelcontextprotocol/sdk（^1\.29\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @a1-x-tech/mcp-google-auth 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @a1-x-tech/mcp-google-auth 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @a1-x-tech/mcp-google-auth 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @a1-x-tech/mcp-google-auth 可以商用吗？

@a1-x-tech/mcp-google-auth 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @a1-x-tech/mcp-google-auth 的下载量有多少？

根据 npm 官方下载统计，@a1-x-tech/mcp-google-auth 在 2026/10/05 – 2026/11/03 这 30 天内被下载 2,580 次，日均约 86 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @a1-x-tech/mcp-google-auth 还在维护吗？

最新版本 0\.1\.2 发布于 2026/11/05（3 天前）；至今共发布 3 个版本，其中过去 12 个月发布了 3 个；首次发布于 2026/09/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。