Gemini Studio Mcp

🎛️ Gemini Studio MCP

Gemini's eyes, ears and long context — inside Claude Desktop.

Meeting recordings, large PDF corpora, internal company data, image and video generation. Gemini does the intake; Claude does the reasoning; the bulk never enters Claude's context.

[](https://github.com/yuting0624/gemini-studio-mcp/actions/workflows/ci.yml) [](LICENSE)

[](https://cloud.google.com/vertex-ai)

---

> Not affiliated with Google or Anthropic. An unofficial, personal project.

🧰 Tools

| Tool | What it does | |---|---| | digest | Reads and summarises documents, images, audio and video from a local path, a Google Drive link or a gs:// URI. Routes by file type automatically: documents get page/section citations, recordings get timestamps, chapters, action items, quotes and on-screen text (OCR). Also answers specific questions | | search_internal | Searches internal company data via Vertex AI Search, returning a generated summary plus source passages | | list_search_engines | Lists the internal search apps available in your project | | savings_report | Totals how much material has been kept out of the calling model's context, and what that was worth | | generate_image | Generates images. Full resolution saved locally, a preview shown inline | | generate_video | Generates video with Veo, reporting progress while it runs | | health_check | Diagnoses auth, project, model reachability and API connectivity, with concrete next steps | | auth_setup | Signs in to Google. Opens a browser — no terminal required |

Every response ends with a usage block (input/output tokens, model, estimated cost).

💰 What it actually saves

An MCP server cannot make a conversation use a cheaper model — the model is chosen before any tool runs. What it can do is keep bulk material out of that model's context, which is where the money is: a conversation re-sends its whole context every turn, so a 40,000-token document left in it is charged again on every turn, while a 1,000-token digest is not.

digest calls therefore report a second line:

usage:   { input_tokens=41021, output_tokens=2773, model=gemini-3.6-flash, estimated_cost_usd=0.082329 }
offload: { tokens_kept_out=40050, tokens_returned=971, destination=claude-opus-5,
           est_cost_avoided_usd=0.20025, net_saved_usd=0.117921, avoided_per_later_turn_usd=0.020025 }

savings_report totals those over time from a local ledger (~/.gemini-mcp/ledger.jsonl, counts only — no file names or content; GEMINI_MCP_LEDGER=off disables it).

Where it does not pay. Below roughly 6,000 input tokens (~20KB of text) the first pass is marginal either way, because Gemini's output is billed at output rates whether or not it saved anything downstream. Measured on a 20KB document: -$0.0038 net before tuning, +$0.0015 after. What decides it is how long the digest comes out, not how large the input was. The savings_report output says so when the total is negative rather than presenting a bare number.

This is why defaults.digestThinkingLevel is LOW rather than left to the model. Thinking tokens are billed as output and none of them reach the caller, so on a digest they are pure cost — on one 24KB test document they were 4,383 of 7,333 output tokens, and turning them down moved that call from -$0.046 to -$0.0007 with no loss of extraction quality.

The figures are estimates, not measurements: token counts come from Gemini's tokenizer and are priced at the destination model's rates from prices.json. Claude on Vertex AI is priced separately from the first-party rates recorded there — check before quoting a customer.

---

🗺️ The same idea, a different surface

Claude keeps the judgement; Gemini absorbs the bulk; whatever Gemini reads stays out of Claude's context. That thesis does not change — who is sitting in front of it does, and that decides the shape it has to take.

| | antigravity-for-claude-code | gemini-studio-mcp (this repo) | |---|---|---| | Surface | Claude Code, in a terminal | Claude Desktop | | For | developers | anyone who does not live in a terminal | | Shape | a plugin that delegates to the agy CLI as a sub-agent | an MCP server exposing tools | | Work | scaffolding, test generation, migrations, first-pass review | documents, recordings, internal search, image & video | | Verb | execute — Gemini writes, Claude verifies | ingest — Gemini reads, Claude reasons |

The split is not cosmetic. A developer can be handed a CLI, a delegation budget and an AGENTS.md, and will use them. A business user opens a chat window and drags in a PDF — no wrapper script, no tier flag, no --dir. So the same routing decision that is an explicit --tier in one is an automatic file-type route in the other, and the cost discipline that is a documented practice there is a number printed on every response here.

They also fail differently, which is the honest reason to keep them apart rather than merge them: delegated writing can silently not happen and has to be verified against the filesystem, while delegated reading can quietly summarise away the one paragraph that mattered and has to be verified against citations. Same models, different failure to defend against.

quorum-review is the third shape — the two models as peers on a pull request rather than conductor and executor. Same author.

---

🔑 Two auth modes

| | Vertex AI mode (recommended) | API key mode | |---|---|---| | Auth | Google account via ADC; auth_setup opens a browser | GEMINI_API_KEY | | Billing | Your own GCP project | Personal/team Google AI billing | | Available tools | All | search_internal / list_search_engines unavailable |

The default is auto: Vertex AI mode when ADC is present, otherwise API key mode.

🚀 Setup

Requirements

• Node.js 20+ (ships with Claude Desktop)
• For Vertex AI mode: a GCP project and the Google Cloud CLI
• For large video files: ffmpeg (optional)

Install

git clone https://github.com/yuting0624/gemini-studio-mcp.git
cd gemini-studio-mcp
npm install
npm run build
node scripts/install-desktop.mjs --project 

install-desktop.mjs merges into claude_desktop_config.json, preserving existing settings and writing a timestamped backup first. Use --dry-run to preview and --remove to unregister.

Restart Claude Desktop, then run health_check in a chat.

Manual configuration

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gemini-studio-mcp": {
      "command": "node",
      "args": ["/path/to/gemini-studio-mcp/dist/index.js"],
      "env": { "GEMINI_MCP_PROJECT_ID": "your-gcp-project" }
    }
  }
}

⚙️ Configuration

~/.gemini-mcp/config.json (environment variables take precedence):

{
  "mode": "auto",                    // auto | vertex | api_key
  "uiLanguage": "en",                // en | ja
  "projectId": "your-gcp-project",
  "locations": {
    "gemini": "global",              // Gemini 3.x is global-only
    "veo": "us-central1",            // Veo is regional-only
    "search": "global"
  },
  "models": {
    "tiers": {
      "flash": "gemini-3.6-flash",
      "flash-lite": "gemini-3.5-flash-lite",
      "pro": "gemini-3.1-pro-preview"
    }
  },
  "defaults": {
    "digestThinkingLevel": "LOW"       // MINIMAL | LOW | MEDIUM | HIGH | auto
  },
  "media": { "preferGcsForVideo": true }
}

Swapping models

When a new model ships, switch to it via config or an environment variable — no code change and no new release:

GEMINI_MCP_TIER_PRO=gemini-3.5-pro

Key variables: GEMINI_MCP_MODE, GEMINI_MCP_UI_LANGUAGE, GEMINI_MCP_PROJECT_ID, GEMINI_API_KEY, GEMINI_MCP_TIER_FLASH, GEMINI_MCP_TIER_PRO, GEMINI_MCP_LOCATION_GEMINI, GEMINI_MCP_LOCATION_VEO, GEMINI_MCP_GCS_BUCKET, GEMINI_MCP_OUTPUT_DIR, GEMINI_MCP_DIGEST_THINKING, GEMINI_MCP_DESTINATION_MODEL, GEMINI_MCP_LEDGER

Reading from Drive and Cloud Storage

digest accepts local paths, https://drive.google.com/... / https://docs.google.com/... links, and gs://bucket/object URIs in the same call.

• gs:// is handed to Vertex by reference — nothing is downloaded, so object size is irrelevant. Vertex AI mode only.
• Drive needs a credential with drive.readonly. ADC minted for cloud-platform alone cannot read Drive; the server detects that and prints the one-off re-auth command rather than reporting the file as missing. Where a broader ADC scope is not allowed, a service account with Drive access works instead. Google Workspace files (Docs, Sheets, Slides) are exported to PDF, which Drive caps at 10MB.
• Local files larger than the inline request ceiling are staged to Cloud Storage and removed afterwards, instead of being refused.

health_check reports whether each configured tier is actually reachable from your project, so it doubles as the post-swap check.

🌍 Regions (important)

Verified against the live API:

• Gemini 3.x models work only on the global endpoint. They return 404 in us-central1.
• Veo is the opposite: regional only (us-central1). It returns 404 on global.

That is why locations are configured per capability rather than once. Leaving the defaults alone is the safe choice.

📦 Handling large media

Vertex AI has no Files API, so oversized files are handled in this order:

1. Within the limit (14MB by default) → sent inline
2. Large audio → transcoded to 16kHz mono with ffmpeg (essentially lossless for speech recognition)
3. Large video and large documents → staged to Cloud Storage without quality loss, then deleted after processing
4. Cloud Storage unavailable → video is downscaled (fine detail such as slide text may become unreadable); documents are refused rather than truncated

Generated images are handled the same way in reverse: the full-resolution file is written to disk and only a downscaled JPEG preview is returned inline, because a generated PNG on its own exceeds the ~1MB MCP response limit.

Video prefers Cloud Storage over compression because downscaling destroys on-screen text, which is much of what makes digest_media useful. The staging bucket gets a 1-day auto-delete lifecycle rule.

🛡️ Recommended tool policy

| Tool | Policy | Why | |---|---|---| | digest, search_internal, list_search_engines, savings_report, health_check | allow | Read-only; an approval prompt every time ruins the experience | | generate_image, generate_video | ask | Higher cost and they leave artifacts behind | | auth_setup | ask | Opens a browser as a side effect |

🪤 Profiles: the thing that wastes an afternoon

Claude Desktop keeps a separate profile per deployment mode. Signing in with third-party inference moves the app to Claude-3p:

| Sign-in | Config | Extensions | |---|---|---| | Claude account | ~/Library/Application Support/Claude/ | same | | Third-party (Vertex/Bedrock) | ~/Library/Application Support/**Claude-3p**/ | same |

Nothing is shared. An extension installed on the Claude-account profile is invisible after switching to Vertex, and a claude_desktop_config.json entry written to the default path is simply not read. The symptom is a server that "is not connected" while every file you inspect looks correct — logs go to ~/Library/Logs/Claude-3p/ too.

scripts/install-desktop.mjs detects both profiles and prints which is which. Target one with --profile 3p or --profile 1p; the default writes to all of them.

🚚 Distribution

Which path applies depends on how Claude Desktop signs in.

| Sign-in | Install path | |---|---| | Claude account | .mcpb double-click, or claude_desktop_config.json | | Third-party inference (Vertex AI / Bedrock) | managedMcpServers, pushed by an administrator |

This matters: users on third-party inference cannot install a .mcpb themselves. Since the whole point of Vertex AI mode is that Gemini usage lands in the customer's own GCP project, that is exactly the audience who needs the managed path — .mcpb is for evaluation and individual use.

managedMcpServers accepts remote (HTTP/SSE) and local stdio servers, so this server can be pushed as-is. It is delivered through the platform's policy channel, not a user-writable file:

| OS | Channel | |---|---| | macOS | MDM configuration profile | | Windows | GPO registry policy | | Linux | /etc/claude-desktop/managed-settings.json |

The value is an array, and each entry carries its own name:

{
  "managedMcpServers": [
    {
      "name": "gemini-studio-mcp",
      "command": "node",
      "args": ["/opt/gemini-studio-mcp/dist/index.js"],
      "env": { "GEMINI_MCP_PROJECT_ID": "your-gcp-project" },
      "toolPolicy": {
        "digest": "allow",
        "search_internal": "allow",
        "list_search_engines": "allow",
        "health_check": "allow",
        "generate_image": "ask",
        "generate_video": "ask",
        "auth_setup": "ask"
      }
    }
  ]
}

toolPolicy accepts allow, ask, ask-session and blocked. It overrides the user's own persistent tool grants, so the profile above is the one that holds. Use ask-session instead of ask for generation if you want approval once per task rather than once per call.

Because a managed deployment installs to a fixed path, build once and ship dist/ (or the bundled server/index.js) to that path — the server needs only Node 20+, which Claude Desktop already provides.

See [deploy/README.md](deploy/README.md) for the macOS profile generator and the Windows/Linux equivalents, and [docs/field-test.md](docs/field-test.md) for the non-engineer test script.

🔒 Privacy

• Files are sent only to Gemini / Vertex AI. No telemetry.
• Generated artifacts and temporary files stay local, under ~/GeminiMCP/outputs/.
• When a large file is staged to Cloud Storage, the bucket lives in your own GCP project, and the object is deleted after the call.
• The savings ledger (~/.gemini-mcp/ledger.jsonl) records token counts and costs only — no file names, prompts or content — and never leaves the machine. GEMINI_MCP_LEDGER=off disables it.

🌐 Language

Messages shown to the user default to English. Japanese is available:

GEMINI_MCP_UI_LANGUAGE=ja

or in ~/.gemini-mcp/config.json:

{ "uiLanguage": "ja" }

This switches errors, health_check output and section headings, and — unless you set defaults.language explicitly — the language digests are written in. Per-call, digest accepts a language argument. When you ask a question without setting it, the answer comes back in the language you asked in. Tool names and descriptions stay English in both cases, because that is what the model reads when choosing a tool.

✨ Convenience behaviour

• Bare filenames work. digest with Day_1_v3.pdf searches Downloads, Desktop and Documents, and lists candidates if several match.
• Chat-upload paths are detected. A path like /mnt/user-data/uploads/foo.mp4 does not exist locally; the error says so and suggests the matching local file.
• Rate limits are absorbed. A 429 is retried with exponential backoff before it ever reaches you.
• Generated files are one command away. Claude Desktop collapses tool-call

blocks, so an inline image preview sits behind a disclosure triangle. Every generation response therefore ends with a ready-to-paste open ... command for the output folder. Forcing inline rendering is not something a server can do: returning a URL does not help (the client will not fetch URLs the user did not paste), and returning the full image trips the ~1MB response cap. A downscaled preview plus an absolute path is the workable s

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yuting0624
• Source: yuting0624/gemini-studio-mcp
• License: MIT
• Homepage: https://github.com/yuting0624/gemini-studio-mcp#readme

Install and usage instructions live in the source repository linked above.