Skip to content
Back to search

gemini-mcp

MCP Server that enables Claude code to interact with Gemini

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/rlabs-inc--gemini-mcp/badge.svg)](/listings/rlabs-inc--gemini-mcp)

HTML

<a href="/listings/rlabs-inc--gemini-mcp"><img src="/api/listings/rlabs-inc--gemini-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

MCP Server for Claude Code

# Using npm (Recommended)
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY npx -y @rlabs-inc/gemini-mcp

# Using bun
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY bunx @rlabs-inc/gemini-mcp

CLI (Global Install)

# Install globally
npm install -g @rlabs-inc/gemini-mcp

# Set your API key once (stored securely)
gcli config set api-key YOUR_KEY

# Now use any command!
gcli search "latest news"
glci image "sunset over mountains" --ratio 16:9

**Get your API key:** Visit [Google AI Studio](https://aistudio.google.com/apikey) - it's free and takes seconds!

Installation Options

# With verbose logging
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY VERBOSE=true bunx -y @rlabs-inc/gemini-mcp

# With custom output directory for generated images/videos
claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY GEMINI_OUTPUT_DIR=/path/to/output bunx -y @rlabs-inc/gemini-mcp

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 545 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # MCP Server Gemini
  2. A Model Context Protocol (MCP) server for integrating Google's Gemini 3 models with Claude Code, enabling powerful collaboration between both AI systems. Now with a beautiful CLI!
  3. [![npm version](https://badge.fury.io/js/@rlabs-inc%2Fgemini-mcp.svg)](https://www.npmjs.com/package/@rlabs-inc/gemini-mcp)
  4. [![MCP Registry](https://img.shields.io/badge/MCP-Registry-blue)](https://registry.modelcontextprotocol.io)
  5. **MCP Registry Support:** Now discoverable in the official MCP ecosystem!
  6. ## Features
  7. | Feature | Description |
  8. |-------------------------------|-----------------------------------------------------------------|
  9. | **Deep Research Agent** | Autonomous multi-step research with web search and citations |
  10. | **Token Counting** | Count tokens and estimate costs before API calls |
  11. | **Text-to-Speech** | 30 unique voices, single speaker or two-speaker dialogues |
  12. | **URL Analysis** | Analyze, compare, and extract data from web pages |
  13. | **Context Caching** | Cache large documents for efficient repeated queries |
  14. | **YouTube Analysis** | Analyze videos by URL with timestamp clipping |
  15. | **Document Analysis** | PDFs, DOCX, spreadsheets with table extraction |
  16. | **4K Image Generation** | Generate images up to 4K with 10 aspect ratios |
  17. | **Multi-Turn Image Editing** | Iteratively refine images through conversation |
  18. | **Video Generation** | Create videos with Veo 2.0 (async with polling) |
  19. | **Code Execution** | Gemini writes and runs Python code (pandas, numpy, matplotlib) |
  20. | **Google Search** | Real-time web information with inline citations |
  21. | **Structured Output** | JSON responses with schema validation |
  22. | **Data Extraction** | Extract entities, facts, sentiment from text |
  23. | **Thinking Levels** | Control reasoning depth (minimal/low/medium/high) |
  24. | **Direct Query** | Send prompts to Gemini 3 Pro/Flash models |
  25. | **Brainstorming** | Claude + Gemini collaborative problem-solving |
  26. | **Code Analysis** | Analyze code for quality, security, performance |
  27. | **Summarization** | Summarize content at different detail levels |
  28. ---
  29. ## Quick Installation
  30. ### MCP Server for Claude Code
  31. ```bash
  32. # Using npm (Recommended)
  33. claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY npx -y @rlabs-inc/gemini-mcp
  34. # Using bun
  35. claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY bunx @rlabs-inc/gemini-mcp
  36. ```
  37. ### CLI (Global Install)
  38. ```bash
  39. # Install globally
  40. npm install -g @rlabs-inc/gemini-mcp
  41. # Set your API key once (stored securely)
  42. gcli config set api-key YOUR_KEY
  43. # Now use any command!
  44. gcli search "latest news"
  45. glci image "sunset over mountains" --ratio 16:9
  46. ```
  47. **Get your API key:** Visit [Google AI Studio](https://aistudio.google.com/apikey) - it's free and takes seconds!
  48. ### Installation Options
  49. ```bash
  50. # With verbose logging
  51. claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY VERBOSE=true bunx -y @rlabs-inc/gemini-mcp
  52. # With custom output directory for generated images/videos
  53. claude mcp add gemini -s user -- env GEMINI_API_KEY=YOUR_KEY GEMINI_OUTPUT_DIR=/path/to/output bunx -y @rlabs-inc/gemini-mcp
  54. ```
  55. ---
  56. ## Available Tools
  57. ### gemini-query
  58. Direct queries to Gemini with thinking level control:
  59. ```
  60. prompt: "Explain quantum entanglement"
  61. model: "pro" or "flash"
  62. thinkingLevel: "low" | "medium" | "high" (optional)
  63. ```
  64. - **low**: Fast responses, minimal reasoning
  65. - **medium**: Balanced (Flash only)
  66. - **high**: Deep reasoning for complex tasks (default)
  67. ### gemini-generate-image
  68. Generate images with Nano Banana Pro (Claude can SEE them!):
  69. ```
  70. prompt: "a futuristic city at sunset"
  71. style: "cyberpunk" (optional)
  72. aspectRatio: "16:9" (1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9)
  73. imageSize: "2K" (1K, 2K, 4K)
  74. useGoogleSearch: false (ground in real-world info)
  75. thinkingLevel: "high" (optional - minimal, low, medium, high)
  76. personGeneration: "ALLOW_ALL" (optional - ALLOW_ALL, ALLOW_ADULT, ALLOW_NONE)
  77. seed: 42 (optional - for reproducible results)
  78. ```
  79. ### gemini-start-image-edit
  80. Start a multi-turn image editing session:
  81. ```
  82. prompt: "a cozy cabin in the mountains"
  83. aspectRatio: "16:9"
  84. imageSize: "2K"
  85. useGoogleSearch: false
  86. thinkingLevel: "high" (optional - minimal, low, medium, high)
  87. personGeneration: "ALLOW_ALL" (optional - ALLOW_ALL, ALLOW_ADULT, ALLOW_NONE)
  88. seed: 42 (optional - for reproducible results)
  89. ```
  90. Returns a session ID for iterative editing.
  91. ### gemini-continue-image-edit
  92. Continue refining an image:
  93. ```
  94. sessionId: "edit-123456789"
  95. prompt: "add snow on the roof and make it nighttime"
  96. ```
  97. ### gemini-end-image-edit
  98. Close an editing session:
  99. ```
  100. sessionId: "edit-123456789"
  101. ```
  102. ### gemini-list-image-sessions
  103. List all active editing sessions.
  104. ### gemini-generate-video
  105. Generate videos using Veo:
  106. ```
  107. prompt: "a cat playing piano"
  108. aspectRatio: "16:9" (optional)
  109. negativePrompt: "blurry, text" (optional)
  110. ```
  111. Video generation is async (takes 1-5 minutes). Use `gemini-check-video` to poll.
  112. ### gemini-check-video
  113. Check video generation status and download when complete:
  114. ```
  115. operationId: "operations/xxx-xxx-xxx"
  116. ```
  117. ### gemini-analyze-code
  118. Analyze code for issues:
  119. ```
  120. code: "function foo() { ... }"
  121. language: "typescript" (optional)
  122. focus: "quality" | "security" | "performance" | "bugs" | "general"
  123. ```
  124. ### gemini-analyze-text
  125. Analyze text content:
  126. ```
  127. text: "Your text here..."
  128. type: "sentiment" | "summary" | "entities" | "key-points" | "general"
  129. ```
  130. ### gemini-brainstorm
  131. Collaborative brainstorming:
  132. ```
  133. prompt: "How could we implement real-time collaboration?"
  134. claudeThoughts: "I think we should use WebSockets..."
  135. maxRounds: 3 (optional)
  136. ```
  137. ### gemini-summarize
  138. Summarize content:
  139. ```
  140. content: "Long text to summarize..."
  141. length: "brief" | "moderate" | "detailed"
  142. format: "paragraph" | "bullet-points" | "outline"
  143. ```
  144. ### gemini-run-code
  145. Let Gemini write and execute Python code:
  146. ```
  147. prompt: "Calculate the first 50 prime numbers and plot them"
  148. data: "optional CSV data to analyze" (optional)
  149. ```
  150. Supports libraries: numpy, pandas, matplotlib, scipy, scikit-learn, tensorflow, and more.
  151. Generated charts are saved to the output directory and returned as images.
  152. ### gemini-search
  153. Real-time web search with citations:
  154. ```
  155. query: "What happened in tech news this week?"
  156. returnCitations: true (default)
  157. ```
  158. Returns grounded responses with inline citations and source URLs.
  159. ### gemini-structured
  160. Get JSON responses matching a schema:
  161. ```
  162. prompt: "Extract the meeting details from this email..."
  163. schema: '{"type":"object","properties":{"date":{"type":"string"},"attendees":{"type":"array"}}}'
  164. useGoogleSearch: false (optional)
  165. ```
  166. ### gemini-extract
  167. Convenience tool for common extraction patterns:
  168. ```
  169. text: "Your text to analyze..."
  170. extractType: "entities" | "facts" | "summary" | "keywords" | "sentiment" | "custom"
  171. customFields: "name, date, amount" (for custom extraction)
  172. ```
  173. ### gemini-youtube
  174. Analyze YouTube videos directly:
  175. ```
  176. url: "https://www.youtube.com/watch?v=..."
  177. question: "What happens at 2:30?"
  178. startTime: "1m30s" (optional, for clipping)
  179. endTime: "5m00s" (optional, for clipping)
  180. ```
  181. ### gemini-youtube-summary
  182. Quick video summarization:
  183. ```
  184. url: "https://www.youtube.com/watch?v=..."
  185. style: "brief" | "detailed" | "bullet-points" | "chapters"
  186. ```
  187. ### gemini-analyze-document
  188. Analyze PDFs and documents:
  189. ```
  190. filePath: "/path/to/document.pdf"
  191. question: "Summarize the key findings"
  192. mediaResolution: "low" | "medium" | "high"
  193. ```
  194. ### gemini-summarize-pdf
  195. Quick PDF summarization:
  196. ```
  197. filePath: "/path/to/document.pdf"
  198. style: "brief" | "detailed" | "outline" | "key-points"
  199. ```
  200. ### gemini-extract-tables
  201. Extract tables from documents:
  202. ```
  203. filePath: "/path/to/document.pdf"
  204. outputFormat: "markdown" | "csv" | "json"
  205. ```
  206. ---
  207. ## Workflow: Claude + Gemini
  208. The killer combination for development:
  209. | Claude | Gemini |
  210. |--------|--------|
  211. | Complex logic | Frontend/UI |
  212. | Architecture | Visual components |
  213. | Backend code | Image generation |
  214. | Integration | React/CSS styling |
  215. | Reasoning | Creative generation |
  216. **Example workflow:**
  217. 1. Ask Claude to design the backend API
  218. 2. Use `gemini-generate-image` for UI mockups
  219. 3. Ask Gemini to generate React components via `gemini-query`
  220. 4. Use multi-turn editing to refine visuals
  221. 5. Let Claude wire everything together
  222. ---
  223. ## Environment Variables
  224. | Variable | Required | Default | Description |
  225. |-------------------------|----------|------------------------------|-------------------------------|
  226. | `GEMINI_API_KEY` | Yes | - | Your Google Gemini API key |
  227. | `GEMINI_OUTPUT_DIR` | No | `./gemini-output` | Where to save generated files |
  228. | `GEMINI_MODEL` | No | - | Override model for init test |
  229. | `GEMINI_PRO_MODEL` | No | `gemini-3-pro-preview` | Pro model (Gemini 3) |
  230. | `GEMINI_FLASH_MODEL` | No | `gemini-3-flash-preview` | Flash model (Gemini 3) |
  231. | `GEMINI_IMAGE_MODEL` | No | `gemini-3-pro-image-preview` | Image model (Nano Banana Pro) |
  232. | `GEMINI_IMAGE_THINKING_LEVEL` | No | `high` | Default thinking level for image generation (minimal, low, medium, high) |
  233. | `GEMINI_VIDEO_MODEL` | No | `veo-2.0-generate-001` | Video model |
  234. | `VERBOSE` | No | `false` | Enable verbose logging |
  235. | `QUIET` | No | `false` | Minimize logging |
  236. | `GEMINI_ENABLED_TOOLS` | No | - | Comma-separated list of tool groups to load (e.g., `query,search,image-gen`) |
  237. | `GEMINI_TOOL_PRESET` | No | - | Preset profile: `minimal`, `text`, `image`, `research`, `media`, `full` |
  238. ---
  239. ## Tool Configuration
  240. By default, all 37 tools are loaded. To reduce context usage, configure which tools to load:
  241. ### Available Presets
  242. | Preset | Tool Groups |
  243. |--------|-------------|
  244. | `minimal` | query, brainstorm |
  245. | `text` | query, brainstorm, analyze, summarize, structured |
  246. | `image` | query, image-gen, image-edit, image-analyze |
  247. | `research` | query, search, deep-research, url-context, document |
  248. | `media` | query, image-gen, image-edit, image-analyze, video-gen, youtube, speech |
  249. | `full` | All 18 tool groups (default) |
  250. ### Using Presets
  251. ```bash
  252. # Minimal - query and brainstorm
  253. GEMINI_TOOL_PRESET=minimal
  254. # Text processing
  255. GEMINI_TOOL_PRESET=text # query, brainstorm, analyze, summarize, structured
  256. # Image workflows
  257. GEMINI_TOOL_PRESET=image # query, image-gen, image-edit, image-analyze
  258. # Research workflows
  259. GEMINI_TOOL_PRESET=research # query, search, deep-research, url-context, document
  260. ```
  261. ### Using Explicit Tool Lists
  262. ```bash
  263. # Only specific tools
  264. GEMINI_ENABLED_TOOLS=query,search,image-gen
  265. ```
  266. ### Combining Preset + Explicit
  267. ```bash
  268. # Start with preset, add extras
  269. GEMINI_TOOL_PRESET=minimal
  270. GEMINI_ENABLED_TOOLS=search,image-gen # Adds to minimal preset
  271. ```
  272. ### Available Tool Groups
  273. | Group | Tools |
  274. |-------|-------|
  275. | `query` | gemini-query |
  276. | `brainstorm` | gemini-brainstorm |
  277. | `analyze` | gemini-analyze-code, gemini-analyze-text |
  278. | `summarize` | gemini-summarize |
  279. | `image-gen` | gemini-generate-image, gemini-image-prompt |
  280. | `image-edit` | gemini-start-image-edit, gemini-continue-image-edit, gemini-end-image-edit, gemini-list-image-sessions |
  281. | `video-gen` | gemini-generate-video, gemini-check-video |
  282. | `code-exec` | gemini-run-code |
  283. | `search` | gemini-search |
  284. | `structured` | gemini-structured, gemini-extract |
  285. | `youtube` | gemini-youtube, gemini-youtube-summary |
  286. | `document` | gemini-analyze-document, gemini-summarize-pdf, gemini-extract-tables |
  287. | `url-context` | gemini-analyze-url, gemini-compare-urls, gemini-extract-from-url |
  288. | `cache` | gemini-create-cache, gemini-query-cache, gemini-list-caches, gemini-delete-cache |
  289. | `speech` | gemini-speak, gemini-dialogue, gemini-list-voices |
  290. | `token-count` | gemini-count-tokens |
  291. | `deep-research` | gemini-deep-research, gemini-check-research, gemini-research-followup |
  292. | `image-analyze` | gemini-analyze-image |
  293. ---
  294. ## Manual Installation
  295. ### Global Install
  296. ```bash
  297. # Using npm
  298. npm install -g @rlabs-inc/gemini-mcp
  299. # Using bun
  300. bun install -g @rlabs-inc/gemini-mcp
  301. ```
  302. ### Claude Code Configuration
  303. ```json
  304. {
  305. "gemini": {
  306. "command": "npx",
  307. "args": ["-y", "@rlabs-inc/gemini-mcp"],
  308. "env": {
  309. "GEMINI_API_KEY": "your-api-key",
  310. "GEMINI_OUTPUT_DIR": "/path/to/save/files"
  311. }
  312. }
  313. }
  314. ```
  315. If you must use a proxy to establish a connection to gemini, replace `xxxx` with your actual proxy port:
  316. ```json
  317. {
  318. "gemini": {
  319. "command": "npx",
  320. "args": ["-y", "@rlabs-inc/gemini-mcp"],
  321. "env": {
  322. "GEMINI_API_KEY": "your-api-key",
  323. "GEMINI_OUTPUT_DIR": "/path/to/save/files",
  324. "HTTP_PROXY": "http://127.0.0.1:xxxx",
  325. "HTTPS_PROXY": "http://127.0.0.1:xxxx"
  326. }
  327. }
  328. }
  329. ```
  330. ---
  331. ## Troubleshooting
  332. ### Rate Limits (429 Errors)
  333. If you're hitting rate limits on the free tier:
  334. - Set `GEMINI_MODEL=gemini-3-flash-preview` to use Flash for init (higher limits)
  335. - Or upgrade to a paid plan
  336. ### Connection Issues
  337. 1. Verify your API key at [Google AI Studio](https://aistudio.google.com/apikey)
  338. 2. Check server status: `claude mcp list`
  339. 3. Try with verbose logging: `VERBOSE=true`
  340. ### Image/Video Issues
  341. - Ensure your API key has access to image/video generation
  342. - Check output directory permissions
  343. - Files save to `GEMINI_OUTPUT_DIR` (default: `./gemini-output`)
  344. - For 4K images, generation takes longer
  345. ---
  346. ### Previous Versions
  347. **0.7.2**
  348. **Beautiful CLI with Themes!** Use Gemini directly from your terminal:
  349. ```bash
  350. # Install globally
  351. npm install -g @rlabs-inc/gemini-mcp
  352. # Set your API key once
  353. gcli config set api-key YOUR_KEY
  354. # Generate images, videos, search, research, and more!
  355. gcli image "a cat astronaut" --size 4K
  356. gcli search "latest AI news"
  357. gcli research "quantum computing applications" --wait
  358. gcli speak "Hello world" --voice Puck
  359. ```
  360. **5 Beautiful Themes:** terminal, neon, ocean, forest, minimal
  361. **CLI Commands:**
  362. - `gcli query` - Direct Gemini queries with thinking levels
  363. - `gcli search` - Real-time web search with citations
  364. - `gcli research` - Deep research agent
  365. - `gcli image` - Generate images (up to 4K)
  366. - `gcli video` - Generate videos with Veo
  367. - `gcli speak` - Text-to-speech with 30 voices
  368. - `gcli tokens` - Count tokens and estimate costs
  369. - `gcli config` - Manage settings
  370. **v0.6.x:** Deep Research, Token Counting, TTS, URL analysis, Context Caching
  371. **v0.5.x:** 30+ tools, YouTube analysis, Document analysis
  372. **v0.4.x:** Code execution, Google Search
  373. **v0.3.x:** Thinking levels, Structured output, 4K images
  374. **v0.2.x:** Image/Video generation with Veo
  375. ---
  376. ## Development
  377. ```bash
  378. git clone https://github.com/rlabs-inc/gemini-mcp.git
  379. cd gemini-mcp
  380. bun install
  381. bun run build
  382. bun run dev -- --verbose
  383. ```
  384. ### Scripts
  385. | Command | Description |
  386. |---------------------|-----------------------------|
  387. | `bun run build` | Build for production |
  388. | `bun run dev` | Development mode with watch |
  389. | `bun run typecheck` | Type check without emitting |
  390. | `bun run format` | Format with Prettier |
  391. | `bun run lint` | Lint with ESLint |
  392. ---
  393. ## License
  394. MIT License
  395. ---
  396. Made with Claude + Gemini working together

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.