# Gemini Studio Mcp

> Gemini's eyes, ears and long context inside Claude Desktop — an MCP server for document/audio/video digest, Vertex AI Search, and image & video generation. Reports what each call keeps out of Claude's context.

- **Type:** MCP server
- **Install:** `agentstack add mcp-yuting0624-gemini-studio-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [yuting0624](https://agentstack.voostack.com/s/yuting0624)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [yuting0624](https://github.com/yuting0624)
- **Source:** https://github.com/yuting0624/gemini-studio-mcp
- **Website:** https://github.com/yuting0624/gemini-studio-mcp#readme

## Install

```sh
agentstack add mcp-yuting0624-gemini-studio-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🎛️ 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**](https://github.com/yuting0624/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**](https://github.com/yuting0624/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](https://cloud.google.com/sdk/docs/install)
- For large video files: [ffmpeg](https://ffmpeg.org/) (optional)

### Install

```bash
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`:

```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):

```jsonc
{
  "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**:

```bash
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`:

```json
{
  "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:

```bash
GEMINI_MCP_UI_LANGUAGE=ja
```

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

```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](https://github.com/yuting0624)
- **Source:** [yuting0624/gemini-studio-mcp](https://github.com/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.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-yuting0624-gemini-studio-mcp
- Seller: https://agentstack.voostack.com/s/yuting0624
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.