Skip to main content
Glama
yumi233

third-party-gemini-mcp

by yumi233
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

第三方 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: RanchHand

配置环境变量

仅支持以下两个变量；不会读取 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.

ParametersJSON Schema
NameRequiredDescriptionDefault
taskYes
contextNo
max_roundsNo
read_filesNo
write_filesNo
workspace_rootNo
expected_outputNo

TDQS

A3.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description adds meaningful behavioral context beyond annotations: it discloses no shell execution, that file writes may be partial on failure, and that file operations require explicit workspace_root and allowlists. These are not captured by the annotations (readOnlyHint false, destructiveHint true, openWorldHint true) and provide actionable safety information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, compact sentence that front-loads the core purpose and then lists constraints. It avoids redundancy and is easy to parse, though it could be slightly more structured with separate sentences for constraints.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description does not explain the output format (no output schema), the semantics of 'task' or 'expected_output', or the multi-round behavior implied by max_rounds. It covers file-handling constraints but leaves several critical aspects unspecified, making it incomplete for an agent to confidently invoke the tool correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, so the description carries the full burden for parameter explanation. It only clarifies semantics for read_files, write_files, and workspace_root (via the allowlist requirement and partial-write warning). Parameters like task, context, max_rounds, and expected_output remain unexplained. Given 7 parameters, this is insufficient compensation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific purpose: 'Gemini Flash text, code and document tasks.' It clearly distinguishes from sibling tools (gemini_vision, image_generate) by modality. It also mentions optional file operations, which adds specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for text/code/document tasks but does not explicitly state when to use this tool over alternatives. It mentions constraints (no shell execution, file allowlist requirements) but gives no explicit when/when-not guidance relative to siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
imagesYes
promptYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the agent knows it's a safe read operation. The description adds valuable behavioral detail: local image paths are read and sent to a proxy, while URLs are passed without local fetching. This clarifies how the tool handles different input types and potential network implications, going beyond the annotation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence with no wasted words. The core purpose is front-loaded ('Analyze or compare up to four images'), followed by a concise behavioral note. Every word earns its place, making it highly efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with only two parameters and no output schema, the description is mostly complete. It covers the essential purpose and input behavior. The main gap is the lack of any mention of what the response contains (e.g., a text analysis result), which might be important for an agent to set expectations. However, given the simplicity and annotations, it is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It explains the images parameter's behavior (local paths vs URLs) and mentions 'up to four images,' which aligns with maxItems. However, it does not describe the prompt parameter's purpose, though that is relatively self-evident. It adds meaningful context for images but not fully for prompt.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Analyze or compare up to four images.' It uses a specific verb (analyze/compare) and resource (images), and implicitly differentiates from siblings like image_generate (which generates rather than analyzes) and gemini_flash (likely a different model). The purpose is unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no explicit guidance on when to use this tool versus alternatives like gemini_flash or image_generate. It does not mention exclusions, prerequisites, or conditions under which another tool would be preferred. The only contextual hint is the tool's name and description, which imply image analysis, but no direct comparison is made.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
promptYes
adapterNoauto

TDQS

A3.8/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=false, openWorldHint=true, and idempotentHint=false. The description adds two useful behavioral facts beyond these: 'Can incur provider charges' (cost warning) and 'URL results are returned without downloading' (return format). These are meaningful additions that help the agent anticipate side effects and output handling. No contradictions with annotations. Given the annotation coverage, a 4 is appropriate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is three sentences, front-loaded with the core purpose, then adding adapter choice, cost warning, and URL return behavior. Every sentence contributes unique information with no redundancy or filler. This is exemplary conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given only two parameters (one required) and no output schema, the description covers the essential points: what it does, how to select an adapter, cost implications, and the fact that results are URLs. It doesn't address error handling, rate limits, or prompt best practices, but for a simple image-generation tool with these annotations and no output schema, it is reasonably complete. A 4 reflects that it's sufficient but not exhaustive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate for parameter meaning. It mentions the 'adapter' parameter with its three enum values, which are already in the schema, and implies the 'prompt' is the text to generate from, but it doesn't elaborate on prompt format or constraints (e.g., style, length). The description adds some value (cost, URL results) but doesn't fully explain the parameters' semantics beyond what the enum and type already show. A baseline of 3 is fair.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's action ('Generate an image') and the resource (a dynamically discovered image model), with the adapter choice ('auto, chat or images') adding specificity. It does not explicitly name or contrast sibling tools like gemini_flash or gemini_vision, so it doesn't fully distinguish itself, but the notion of a dynamic model with adapter selection implies a flexible generic alternative. Hence a 4 rather than a 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives some context on how to choose the adapter ('auto, chat or images'), which is internal to the tool, but offers no guidance on when to use this tool versus its siblings (gemini_flash, gemini_vision). There is no explicit mention of alternatives or exclusions; usage is implied by the 'dynamically discovered' phrasing. This is adequate but not explicit, so a 3.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.0
    • First observedgemini_flash
    • First observedgemini_vision
    • First observedimage_generate
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Outsource MCP

    gwbischof
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that enables AI applications to access 20+ model providers (including OpenAI, Anthropic, Google) through a unified interface for text and image generation.
    2
    30
    MIT

  • RanchHand

    anteew
    -
    license
    C
    quality
    Not graded
    maintenance
    Enables interaction with OpenAI-compatible APIs (like Ollama) through MCP tools. Provides access to chat completions, model listings, and embeddings generation from local or remote OpenAI-style endpoints.
    3
    -

  • spiderswitch

    hiddenpath
    A
    license
    Not graded
    quality
    B
    maintenance
    MCP server that enables agents to dynamically switch between multiple AI models (OpenAI, Anthropic, Google, etc.) with unified protocol-driven configuration and capability discovery.
    Apache 2.0