Gemini Oauth MCP

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应用程序，请：

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

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

1. 设置环境变量：

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을 실행해줘

行为方式：

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

示例响应：

[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 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认证页面上选择了“拒绝”。

解决方法：

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

“无法获取用户信息”

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

解决方法：

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

Rate Limit（429错误）

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

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

解决方法：

1. 添加新帐户：

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

1. 等待：

   quota_status로 리셋 시간 확인 후 대기

1. 请求减少：

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

确认禁用Rate Limit

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

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

连接错误

“启动MCP服务器失败”

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

解决方法：

1. 端口更改：

   export OAUTH_PORT=51122

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

   lsof -i :51121

1. 终止服务器进程：

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

“连接被拒绝”

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

解决方法：

1. 验证服务器运行：

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

1. 验证MCP设置路径：

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

1. 检查命令路径：

   # npx 설치 확인
   which npx

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

令牌更新错误

“令牌刷新失败”

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

解决方法：

1. 重新认证帐户：

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

1. 验证Google帐户的安全性：

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

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

- 在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

添加新工具

1. 定义和实施工具 (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: "결과" }],
     };
   }

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

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

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

1. 添加测试 (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工具列表

认证相关

创建相关

设置相关

监控

响应格式

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

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

错误处理

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

[ERROR] 작업 실패

Reason: 구체적인 오류 원인

许可证

麻省理工学院

参考

• 模型上下文协议（MCP）
• 谷歌OAuth 2.0
• API双子星
• 开放代码反重力认证