gemini oauth mcp

通过Google OAuth身份验证使用Gemini API的MCP服务器。无需API密钥即可通过Google帐户进行身份验证，以利用免费配额。

特点

Google OAuth 2.0认证 -无需API密钥，通过个人帐户进行身份验证
使用免费配额 -降低成本，利用免费帐户的配额
多帐户轮换 -避开Rate Limit，巡回多个账户的配额
配额跟踪 -跟踪每个帐户的请求统计和重置时间
自动令牌续订 -自动更新Access Token，管理Refresh Token
基于stdio的通信 -符合MCP协议标准

技术堆栈

运行时：Node.js 18+
语言：TypeScript 5.x
框架：@modelcontextprotocol/sdk 1.x
验证：佐德3.25+
构建：tsup
测试：邀请

安装

npx（建议）

npx gemini-oauth-mcp

手动安装

# 저장소 클론
git clone https://github.com/yourusername/gemini-oauth-mcp.git
cd gemini-oauth-mcp

# 의존성 설치
npm install

# 빌드
npm run build

# 실행
npm run build && node dist/index.js

环境变量

默认值为：必要时可以覆盖环境变量。

# OAuth 콜백을 받을 로컬 서버 포트 (기본값: 51121)
export OAUTH_PORT=51121

# 로그 레벨 (기본값: info)
# 가능한 값: debug, info, warn, error
export LOG_LEVEL=info

# 기본 모델 (기본값: gemini-2.5-flash)
# Gemini 3.0 모델은 Antigravity 인증 필요
export GEMINI_DEFAULT_MODEL=gemini-2.5-flash

自定义OAuth设置（可选）

默认情况下，使用内置的OAuth凭据。要使用自己的OAuth应用程序，请：

谷歌云控制台在中创建OAuth 2.0客户端ID
应用程序类型： 桌面应用程序 选择
添加批准的重定向URI： http://localhost:51121/oauth-callback
激活以下范围：

- https://www.googleapis.com/auth/cloud-platform - https://www.googleapis.com/auth/userinfo.email

设置环境变量：

export GEMINI_CLIENT_ID=your-client-id.apps.googleusercontent.com
export GEMINI_CLIENT_SECRET=your-client-secret
export GEMINI_REDIRECT_URI=http://localhost:51121/oauth-callback  # 선택사항

注意： Gemini 3.0型号（Antigravity模式）需要特殊的OAuth设置。建议使用默认内置凭据。

MCP设置

克劳德代码（.Claude/mcp.json）

{
  "mcpServers": {
    "gemini-oauth": {
      "command": "npx",
      "args": ["gemini-oauth-mcp"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

游标（.Cursor/mcp.json）

{
  "mcpServers": {
    "gemini-oauth": {
      "command": "npx",
      "args": ["gemini-oauth-mcp"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

手动安装（本地版本）

{
  "mcpServers": {
    "gemini-oauth": {
      "command": "node",
      "args": ["/path/to/gemini-oauth-mcp/dist/index.js"],
      "env": {
        "LOG_LEVEL": "info"
      }
    }
  }
}

使用方法

添加帐户

auth_login 使用工具添加新的Google帐户。

사용자: auth_login을 실행해줘

行为方式：

通过创建PKCE和State增强OAuth 2.0安全性
在默认浏览器中自动打开Google认证页面
用户使用Google帐户登录和授权
从本地回调服务器接收验证码
将代码交换为Access Token和Refresh Token
保存令牌并注册帐户

示例响应：

[OK] Successfully authenticated!

  Account: user@gmail.com
  Status:  Ready to use
  Total:   1 account registered

查看已注册帐户列表

auth_list 使用工具检查所有注册的帐户和状态。

사용자: 등록된 계정을 보여줘

示例响应：

Registered Accounts (2)
═══════════════════════════════════════════════════════════

  #  Email                  Status         Last Used
  ─  ──────────────────────  ─────────────  ──────────────────

  1  user1@gmail.com        ● Active       just now
  2  user2@gmail.com        ○ Ready        2 hours ago

═══════════════════════════════════════════════════════════

Status Legend:
  ● Active   - Currently in use
  ○ Ready    - Available for use
  ◌ Limited  - Rate limited, waiting for reset

状态含义：

活动（●）：当前使用的帐户
准备就绪（○）：处于可用状态的帐户
有限公司（◌）：Rate Limit状态，等待重置

检查当前认证状态

auth_status 使用工具检查当前的身份验证状态和令牌有效期。

사용자: 현재 인증 상태를 확인해줘

示例响应：

Authentication Status
═══════════════════════════════════════════════════════════

  Status:         ✓ Authenticated
  Active Account: user@gmail.com
  Token Expiry:   50 minutes remaining

  Accounts:       2 registered
  Rate Limited:   0 accounts
  Available:      2 accounts

═══════════════════════════════════════════════════════════

删除帐户

auth_remove 删除使用工具注册的帐户。

사용자: user2@gmail.com을 제거해줘

参数：

account_id （string）：要删除的帐户的ID或电子邮件地址

示例响应：

✓ Account removed

  Removed: user2@gmail.com
  Remaining: 1 account

限制：

无法删除最后一个帐户（至少需要一个帐户）
建议在添加新帐户后删除现有帐户

创建交互式响应

chat 使用工具与Gemini AI对话。

사용자: 파리에 대해 알려줘

参数：

message （string，必需）：要发送的消息
model （string，可选）：要使用的模型名（默认值： gemini-3.0-flash)

支持型号：

型号	说明	认证模式
`gemini-2.5-flash` 快速且经济实惠（默认）standard
`gemini-2.5-pro` 长上下文稳定性standard
`gemini-2.0-flash` 新一代功能standard
`gemini-1.5-flash` 稳定的快速模型standard
`gemini-1.5-pro` 稳定的高性能standard
`gemini-3.0-flash`	Pro级性能的快速模型	antigravity
`gemini-3.0-pro`	最佳推论antigravity

注： Gemini 3.0型号需要防重力认证（auth_login mode="antigravity")

示例响应：

[Gemini 2.5 Flash via user@gmail.com]

파리는 프랑스의 수도이자 가장 큰 도시입니다. 센강을 따라
펼쳐진 파리는 세계적으로 문화, 예술, 과학의 중심지로 알려져 있습니다...

제로 꺼진다 아이펠탑, 루브르 박물관, 노트르담 대성당 등
많은 명소들이 있습니다.

自动处理Rate Limit： 如果出现Rate Limit（429），则会自动切换到以下帐户：

⚠ Rate limit on user1@gmail.com
  → Switching to user2@gmail.com

[Gemini 2.5 Flash via user2@gmail.com]

파리는 프랑스의 수도입니다...

创建内容

generate_content 使用工具创建长格式的内容。

사용자: 블로그 포스트를 작성해줘. 제목: "AI의 미래"

参数：

prompt （string，必需）：内容创建提示
model （string，可选）：要使用的模型名（默认值： gemini-3.0-flash)

示例响应：

[Gemini 2.5 Flash via user@gmail.com]

# AI의 미래

## 서론
인공지능 기술은 현대 사회의 가장 중요한 혁신 중 하나입니다...

## 본론
1. 기술 발전
   - 머신러닝의 고도화
   - 자연어 처리의 진화
   ...

Rate Limit处理： chat 应用与工具相同的自动帐户转换机制。

验证设置

config_get 使用工具检查当前设置。

사용자: 현재 설정을 보여줘

示例响应：

Current Configuration
═══════════════════════════════════════════════════════════

  Setting         Value
  ──────────────  ──────────────────────────────────────────

  Default Model   gemini-3.0-flash
  Config Path     /Users/user/.config/gemini-oauth-mcp

═══════════════════════════════════════════════════════════

Available Models:
  1. gemini-3.0-flash (current)
  2. gemini-3.0-pro
  3. gemini-2.5-flash
  4. gemini-2.5-pro

更改默认模型

config_set 使用工具更改缺省模型。

사용자: 기본 모델을 gemini-3.0-pro로 변경해줘

参数：

key （string，必需）：设置键（default_model)
value （string，必需）：设置值

示例响应：

✓ Default model set to: gemini-3.0-pro

This setting is saved and will persist across sessions.

支持型号： 请参阅上面“创建交互式响应”部分中的“模型表”。

快速转换型号

使用快捷工具可以快速切换基本模型：

사용자: use_flash 실행해줘   → gemini-3.0-flash로 전환
사용자: use_pro 실행해줘    → gemini-3.0-pro로 전환
사용자: use_flash_20 실행해줘 → gemini-2.0-flash로 전환
사용자: use_flash_15 실행해줘 → gemini-1.5-flash로 전환
사용자: use_pro_15 실행해줘  → gemini-1.5-pro로 전환

或 model 使用工具查看和更改当前模型：

사용자: model 실행해줘              → 현재 기본 모델 표시
사용자: model name="gemini-2.5-pro" → 해당 모델로 변경

确认配额

quota_status 使用工具查看所有帐户的配额使用情况。

사용자: 할당량 상태를 보여줘

示例响应：

Quota Status
═══════════════════════════════════════════════════════════

  Account            Requests       Status
  ─────────────────  ────────────   ──────────────────────

  user1@gmail.com    45/1000        ████████░░ 45%
  user2@gmail.com    950/1000       ██████████ 95%
  user3@gmail.com    1200/1000      ██████████ Limited

═══════════════════════════════════════════════════════════

  Total Available:     345 requests

  Rate Limited:        1 account (user3@gmail.com)
  Next Reset:          2 hours

═══════════════════════════════════════════════════════════

显示项目：

账户：电子邮件地址（最多显示20个字符，超过“……”处理）
请求：：使用的请求数/限制
状态：升级条和使用率/限制状态
可用总数：所有帐户的可用请求总数
速率限制：处于Rate Limit状态的帐户数和电子邮件
下一次重置：下次配额重置时间

故障射击

认证失败

“身份验证超时”

原因： 5分钟内无法完成Google身份验证。

解决方法：

# auth_login 다시 실행
# 브라우저에서 Google 인증 완료 (5분 내)
# 또는 OAUTH_PORT 환경 변수 확인
export OAUTH_PORT=51121

“用户拒绝访问”

原因： 在Google认证页面上选择了“拒绝”。

解决方法：

再 auth_login 执行
在Google认证页面上选择“继续”或“允许”
批准所需权限

“无法获取用户信息”

原因： 验证成功，但无法查询用户信息

解决方法：

验证Google帐户的互联网连接
再 auth_login 尝试
尝试其他Google帐户

Rate Limit（429错误）

“所有账户都有利率限制”

原因： 所有注册的帐户都处于Rate Limit状态。

解决方法：

添加新帐户：

   auth_login을 실행하여 새로운 Google 계정 추가

等待：

   quota_status로 리셋 시간 확인 후 대기

请求减少：

   API 호출 빈도 감소 또는 배치 처리 방식 변경

确认禁用Rate Limit

사용자: 할당량 상태를 확인해줘

Next Reset 如果时间为“now”或过去的时间，则配额处于重置状态。

连接错误

“启动MCP服务器失败”

原因： 服务器启动失败，端口可能冲突

解决方法：

端口更改：

   export OAUTH_PORT=51122

检查端口冲突（MacOS/Linux）：

   lsof -i :51121

终止服务器进程：

   # 이전 프로세스 종료 후 재시작
   pkill -f "node dist/index.js"
   npm run build && node dist/index.js

“连接被拒绝”

原因： MCP客户端无法连接到服务器

解决方法：

验证服务器运行：

   # 새 터미널에서 서버 수동 실행
   npm run build && node dist/index.js

验证MCP设置路径：

- 克劳德代码： .claude/mcp.json - 光标： .cursor/mcp.json

检查命令路径：

   # npx 설치 확인
   which npx

   # 또는 절대 경로 사용
   /usr/local/bin/node /full/path/to/dist/index.js

令牌更新错误

“令牌刷新失败”

原因： Refresh Token无法获得新的Access Token。

解决方法：

重新认证帐户：

   계정 제거: auth_remove user@gmail.com
   계정 추가: auth_login

验证Google帐户的安全性：

- https://myaccount.google.com/security验证登录 - 删除可疑的登录活动

设置应用程序密码（启用两步验证时）：

- 在Google帐户安全设置中生成应用程序密码 - 尝试重新认证

记录和调试

启用调试日志

export LOG_LEVEL=debug
npm run build && node dist/index.js

令牌存储位置

# macOS/Linux
~/.config/gemini-oauth-mcp/

# Windows
%APPDATA%\gemini-oauth-mcp\

验证已保存的帐户

ls -la ~/.config/gemini-oauth-mcp/
# storage.json 파일에 저장됨

开发

项目结构

gemini-oauth-mcp/
├── src/
│   ├── index.ts              # 진입점, stdio 서버 시작
│   ├── server.ts             # MCP 서버 설정, 도구 등록
│   ├── tools/
│   │   ├── auth.ts           # auth_login, auth_list, auth_remove, auth_status
│   │   ├── chat.ts           # chat 도구
│   │   ├── generate.ts       # generate_content 도구
│   │   ├── quota.ts          # quota_status 도구
│   │   └── index.ts          # 도구 내보내기
│   ├── auth/
│   │   ├── oauth.ts          # Google OAuth 2.0 구현
│   │   ├── storage.ts        # 계정 저장소
│   │   └── token.ts          # 토큰 관리
│   ├── accounts/
│   │   ├── manager.ts        # 계정 관리
│   │   ├── rotator.ts        # Rate Limit 시 계정 전환
│   │   ├── quota.ts          # 할당량 트래킹
│   │   └── index.ts          # 내보내기
│   ├── api/
│   │   ├── client.ts         # Gemini API 클라이언트
│   │   ├── transform.ts      # 응답 변환
│   │   └── index.ts          # 내보내기
│   └── utils/
│       ├── config.ts         # 설정 (포트, 로그 레벨)
│       ├── logger.ts         # 로깅
│       ├── errors.ts         # 커스텀 에러
│       └── index.ts          # 내보내기
├── tests/
│   ├── unit/                 # 단위 테스트
│   └── integration/          # 통합 테스트
├── dist/                     # 빌드 출력
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── README.md

构建和测试

# 의존성 설치
npm install

# 개발 모드 (watch)
npm run dev

# 프로덕션 빌드
npm run build

# 테스트 (1회)
npm run test

# 테스트 (watch 모드)
npm run test:watch

# 린트 검사
npm run lint

# 자동 형식화
npm run format

# 타입 검사
npm run typecheck

添加新工具

定义和实施工具 (src/tools/new-tool.ts):

   import { z } from "zod";

   export const newTool = {
     name: "new_tool",
     description: "새로운 도구 설명",
     inputSchema: z.object({
       param: z.string().describe("파라미터 설명"),
     }),
   };

   export async function handleNewTool(args: { param: string }): Promise {
     // 구현
     return {
       content: [{ type: "text", text: "결과" }],
     };
   }

在服务器上注册 (src/server.ts):

   import { newTool, handleNewTool } from "./tools/new-tool.js";

   server.registerTool(newTool.name, newTool, handleNewTool);

添加测试 (tests/integration/new-tool.test.ts):

   describe("new_tool", () => {
     it("should work correctly", async () => {
       const result = await handleNewTool({ param: "test" });
       expect(result.content[0].text).toContain("결과");
     });
   });

API文档

MCP工具列表

认证相关

工具名	输入	说明
`auth_login`	`mode?`	添加Google帐户（mode:“standard”“antigravity”）
`auth_list`	无	已注册帐户列表
`auth_remove`	`account_id`	删除帐户
`auth_status`	无	验证状态检查

创建相关

工具名	输入	说明
`chat`	`message`, `model?`	交互式响应
`generate_content`	`prompt`, `model?`	创建内容
`gemini_generate_text`	`prompt`, `model?`	generate_content别名

设置相关

工具名	输入	说明
`config_get`	无	检查当前设置
`config_set`	`key`, `value`	更改设置
`model`	`name?`	检查/更改默认型号
`use_flash`	无	切换到gemini-3.0-flash
`use_pro`	无	切换到gemini-3.0-pro
`use_flash_20`	无	切换到gemini-2.0-flash
`use_flash_15`	无	切换到gemini-1.5-flash
`use_pro_15`	无	切换到gemini-1.5-pro

监控

工具名	输入	说明
`quota_status`	无	配额现状
`ping`	无	检查服务器状态

响应格式

所有工具都返回以下格式的MCP Tool Response：

{
  content: [
    {
      type: "text",
      text: "응답 텍스트"
    }
  ],
  isError?: boolean  // true면 에러 응답
}

错误处理

所有错误 isError: true与一起返回用户友好的消息：

[ERROR] 작업 실패

Reason: 구체적인 오류 원인

许可证

麻省理工学院

Gemini Oauth MCP

快速接入

详细介绍

gemini oauth mcp

特点

技术堆栈

安装

npx（建议）

手动安装

环境变量

自定义OAuth设置（可选）

MCP设置

克劳德代码（.Claude/mcp.json）

游标（.Cursor/mcp.json）

手动安装（本地版本）

使用方法

添加帐户

查看已注册帐户列表

检查当前认证状态

删除帐户

创建交互式响应

创建内容

验证设置

更改默认模型

快速转换型号

确认配额

故障射击

认证失败

“身份验证超时”

“用户拒绝访问”

“无法获取用户信息”

Rate Limit（429错误）

“所有账户都有利率限制”

确认禁用Rate Limit

连接错误

“启动MCP服务器失败”

“连接被拒绝”

令牌更新错误

“令牌刷新失败”

记录和调试

启用调试日志

令牌存储位置

验证已保存的帐户

开发

项目结构

构建和测试

添加新工具

API文档

MCP工具列表

响应格式

错误处理

许可证

参考

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP