Skip to main content
Glama
third-party-gemini-mcp

third-party-gemini-mcp

by yumi233

第三方 Gemini MCP

Unofficial MCP server for OpenAI-compatible model proxy APIs.

这是非官方项目,不属于 Google、Gemini 或 OpenAI 官方产品。通过 stdio 提供文本任务、视觉理解和图像生成;API 地址和凭据只从环境变量读取。当前版本为 0.1.0。

安装

需要 Node.js 22.13+(22 LTS)或 24+ 和 npm。先从你发布的仓库 clone,进入仓库根目录:

git clone https://github.com/yumi233/third-party-gemini-mcp.git
cd third-party-gemini-mcp
npm install
npm run build
npm run lint
npm test

已有锁文件时,CI 和其他电脑优先使用 npm ci。安装后运行的是 dist/index.js。本项目尚未发布 npm 包,不要假定同名 npx 包由本项目维护。

Related MCP server: OpenAI Assistant MCP Server

配置环境变量

仅支持以下两个变量;不会读取 Codex 配置文件,也没有默认代理地址或 Key。BASE_URL 是完整的 API 前缀,通常包含 /v1;程序不会自动补 /v1。

GEMINI_PROXY_BASE_URL=https://your-openai-compatible-proxy.example/v1
GEMINI_PROXY_API_KEY=your_api_key_here

.env.example 只有占位值。复制为 .env 后,默认不会自动加载;可通过 Node 的 --env-file 明确加载。真实 Key 不要写进版本控制、截图或日志。

Windows PowerShell(当前会话):

$env:GEMINI_PROXY_BASE_URL = 'https://your-openai-compatible-proxy.example/v1'
$env:GEMINI_PROXY_API_KEY = 'your_api_key_here'
node dist/index.js

macOS/Linux:

export GEMINI_PROXY_BASE_URL='https://your-openai-compatible-proxy.example/v1'
export GEMINI_PROXY_API_KEY='your_api_key_here'
node dist/index.js

stdio 服务启动后等待 MCP 消息,终端没有输出是正常的。标准输出只用于 MCP 协议。

Codex 注册

在 Codex MCP 配置中加入以下示例,并把示例路径替换为安装目录。凭据从 Codex 进程环境传递;桌面应用需要在设置环境变量后重新启动,并确保启动它的环境包含这些变量。

Windows:

[mcp_servers.gemini-proxy]
command = "node"
args = ['C:\path\to\gemini-proxy-mcp\dist\index.js']
env_vars = ["GEMINI_PROXY_BASE_URL", "GEMINI_PROXY_API_KEY"]
tool_timeout_sec = 900

macOS/Linux:

[mcp_servers.gemini-proxy]
command = "node"
args = ["/path/to/gemini-proxy-mcp/dist/index.js"]
env_vars = ["GEMINI_PROXY_BASE_URL", "GEMINI_PROXY_API_KEY"]
tool_timeout_sec = 900

也可将 args 设置为 ['--env-file=C:\path\to\gemini-proxy-mcp\.env', 'C:\path\to\gemini-proxy-mcp\dist\index.js'],明确加载本地凭据文件。该文件须限制本机访问权限并保持在 Git 之外。

参考:Codex MCP documentation。本次该站点返回 HTTP 403,未能在线复核这些宿主配置字段;实际注册请以所安装 Codex 的配置说明为准。服务端 stdio 和工具发现另有自动测试。连接后应能看到下面三个工具。

MCP tools

工具

输入

行为

gemini_flash

task,可选 context、expected_output

自动选择 Gemini Flash,进行文本、代码、文档和日志分析

gemini_vision

prompt、images

理解或比较 1–4 张图片;每项使用 path 或 url 之一

image_generate

prompt,可选 adapter

自动选择图像模型;返回 MCP 图片块或图片 URL

示例参数:

{"task":"检查这段代码的边界情况","context":"function add(a,b) { return a+b; }"}
{"prompt":"分析木材、连接结构和比例","images":[{"url":"https://images.example/chair.png"}]}
{"prompt":"白色背景上的现代木椅产品效果图","adapter":"auto"}

本地视觉图片用 {"path":"/absolute/path/chair.png"} 或 Windows 绝对路径。图片会上传到配置的代理。支持 PNG/JPEG/GIF/WebP,每张最多 8 MiB;拒绝目录、链接、网络路径和 Windows alternate data stream。检查签名不等同于完整图像解码验证。

Flash 也支持受限文件任务:明确传入绝对 workspace_root,以及使用 / 的相对路径 read_files / write_files 白名单。默认两者为空。模型只能读取已批准的文件、对已批准的现有文件做一次唯一匹配替换;不会创建文件、执行 shell 或运行测试代码。单文件最多 128 KiB。max_rounds 默认 6,上限 8。返回实际 model、summary、audit 和 incomplete;失败可能发生在部分编辑之后,须检查工作区差异。

模型发现和路由

首次工具调用时请求 GET {BASE_URL}/models,缓存 5 分钟;并发调用共享发现请求。列出 MCP 工具不访问代理。缓存失效后刷新失败会报告错误,不使用过期模型偷偷降级。

标准返回形状是 {"data":[{"id":"model-id"}]}。可选扩展 capabilities: ["text","vision","image"] 是本项目定义的明确能力声明;提供时优先使用并将其视为完整声明,不是所有代理都支持这一扩展。没有能力元数据时才采用名称规则:

  • 文本:Gemini Flash,排除图像、音频、TTS 和 embedding;数字版本由高到低,同版本优先非 Lite。

  • 视觉:优先明确的 vision 能力,否则推断普通 Gemini 模型或含 vision 的模型;不会把名字含 image 自动当作视觉理解能力。

  • 图像:明确 image 能力或 image/imagen/dall-e 家族。默认家族顺序集中在 src/models/routing.ts 的 defaultPolicy,可更换;没有写死具体模型版本。

名称推断不保证代理实际提供该能力。路由改变只需要修改集中策略;代理私有 metadata 字段需在 discovery 层明确适配。返回实际使用的模型,不会在出错后悄悄切换其他模型或协议。

API 与图像适配

文本和视觉使用 POST {BASE_URL}/chat/completions,非流式 choices[0].message.content。不使用 Responses API。Flash 文件任务还要求代理支持 OpenAI-compatible function tool calls。

adapter

端点

说明

chat

/chat/completions

发送 modalities: ["text","image"]

images

/images/generations

发送 model、prompt、n: 1

auto

先 chat

仅 HTTP 404/405/501 时尝试 images

支持 data[].b64_json、data[].url、message 的 image_url 内容块和 images 数组,以及文本中的 data URL / Markdown 图片。最多返回 4 张图片。不自动下载远程图片,URL 可由宿主展示或另行获取。代理支持不同参数时可实现 ImageProviderAdapter;自动模式不会穷举私有协议。

每次请求超时 60 秒,包含响应体读取;解压后响应体上限 24 MiB,禁止 HTTP 重定向。发现请求对 429/500/502/503/504 最多重试两次。POST 不自动重试,避免重复计费或重复任务;超时、无图和 HTTP 500 时自动模式也不再发起第二次生成。

测试

npm run build
npm run lint
npm test
npm run test:integration

最后一个命令默认跳过真实请求。手动联调需要已设置的环境变量,并明确启用:

npm run test:integration -- --run
npm run test:integration -- --run --vision /absolute/path/sample.png
npm run test:integration -- --run --image --adapter chat

图片联调可能计费;脚本只输出模型和通过状态,不输出图片内容、Key 或完整响应。CI 不调用真实代理。GitHub Actions 覆盖 Windows、Linux、macOS 和 Node 22/24;本机通过不代表其他平台已经实际通过 CI。

故障排查和迁移

  • 启动失败:检查两个环境变量、Node 版本和是否已构建。Key 不能带换行。

  • HTTP 401/403:检查 Key 和权限;错误不回显响应体或 Authorization。

  • HTTP 404:检查 BASE_URL 是否包含代理所需前缀、模型和端点是否受支持。

  • HTTP 500/503:代理暂时不可用;生成请求不自动重试,可由用户决定重试。

  • No compatible model:查看代理 /models 返回,核对命名或能力扩展。

  • No supported image:选择已确认的 chat / images,或新增适配器。文字成功不表示图片生成成功。

  • 超时:单请求上限是 60 秒;Flash 多轮任务更长,宿主 timeout 应覆盖整个调用。

  • 从旧 gemini-worker 迁移:server.mjs 留作启动兼容桥,但需先 build。隐式读取 Codex 凭据、默认上级工作目录、GEMINI_WORKSPACE_ROOT 和 test_files 已移除。文件任务需显式 workspace_root;新的严格 schema 会拒绝旧的额外字段。

架构和发布

src/index.ts → server.ts → tools/{flash,vision,image}.ts
                         → models/{discovery,routing}.ts
                         → api/{client,image-adapters}.ts
                         → utils/{data,image}.ts + tools/workspace.ts
tests/              mock、权限边界、MCP 内存与 stdio 测试
scripts/integration.ts    可选真实代理联调

发布前运行 npm pack --dry-run 并检查包文件,确认许可证、仓库名及维护者信息,审计整个 Git 历史。项目仓库:https://github.com/yumi233/third-party-gemini-mcp。不要提交 .env、本地图片、生成物和日志。参见 SECURITY.md、CONTRIBUTING.md 和 CHANGELOG.md。

Available Tools

3 tools
gemini_flashA
Destructive

Gemini Flash text, code and document tasks. Optional file reads and exact edits require explicit workspace_root and relative file allowlists. No shell execution. File writes may be partial on failure.

Inputs: task (required), context, max_rounds, read_files, +3 more.

gemini_visionA
Read-only

Analyze or compare up to four images. Explicit local image paths are read and sent to the configured proxy; URLs are passed to the proxy without local fetching.

Inputs: images (required), prompt (required).

image_generateA

Generate an image using a dynamically discovered image model. Choose auto, chat or images adapter. Can incur provider charges. URL results are returned without downloading.

Inputs: prompt (required), adapter.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: text/code/document processing, image analysis, and image generation. No overlap in functionality, so an agent can easily select the right tool.

    Naming Consistency3/5

    Two tools use the 'gemini_' prefix (gemini_flash, gemini_vision) while the third uses an action-oriented name (image_generate). This mixed convention is somewhat inconsistent, though each name is still descriptive and understandable.

    Tool Count4/5

    With only 3 tools, the set is slightly thin but still reasonably scoped for a focused Gemini API wrapper. The tools cover the core text, vision, and generation capabilities without unnecessary bloat.

    Completeness4/5

    The tool surface covers the primary Gemini modalities (text, vision, image generation), but could be missing other capabilities like embeddings, audio, or fine-tuning. For a general-purpose MCP server, the current set is functional but not exhaustive.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers