Skip to content
Back to search

gemini-bridge

A lightweight MCP server bridging AI agents to Google's Gemini AI via official CLI

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/elyin--gemini-bridge/badge.svg)](/listings/elyin--gemini-bridge)

HTML

<a href="/listings/elyin--gemini-bridge"><img src="/api/listings/elyin--gemini-bridge/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.

Prerequisites

1. **Install Gemini CLI**:

   npm install -g @google/gemini-cli

2. **Authenticate with Gemini**:

   gemini auth login

3. **Verify installation**:

   gemini --version

Installation

**🎯 Recommended: PyPI Installation**

# Install from PyPI
pip install gemini-bridge

# Add to Claude Code with uvx (recommended)
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

**Alternative: From Source**

# Clone the repository
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge

# Build and install locally
uvx --from build pyproject-build
pip install dist/*.whl

# Add to Claude Code
claude mcp add gemini-bridge -s user -- uvx gemini-bridge

**Development Installation**

# Clone and install in development mode
git clone https://github.com/shelakh/gemini-bridge.git
cd gemini-bridge
pip install -e .

# Add to Claude Code (development)
claude mcp add gemini-bridge-dev -s user -- python -m src

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 Β· 589 lines

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

  1. # Gemini Bridge
  2. ![CI Status](https://github.com/eLyiN/gemini-bridge/actions/workflows/ci.yml/badge.svg)
  3. ![PyPI Version](https://img.shields.io/pypi/v/gemini-bridge)
  4. ![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)
  5. ![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)
  6. ![MCP Compatible](https://img.shields.io/badge/MCP-compatible-green.svg)
  7. ![Gemini CLI](https://img.shields.io/badge/Gemini-CLI-blue.svg)
  8. A lightweight MCP (Model Context Protocol) server that enables AI coding assistants to interact with Google's Gemini AI through the official CLI. Works with Claude Code, Cursor, VS Code, and other MCP-compatible clients. Designed for simplicity, reliability, and seamless integration.
  9. ## ✨ Features
  10. - **Direct Gemini CLI Integration**: Zero API costs using official Gemini CLI
  11. - **Three MCP Tools**: Basic queries, file analysis, and web search capabilities
  12. - **Stateless Operation**: No sessions, caching, or complex state management
  13. - **Production Ready**: Robust error handling with configurable 60-second timeouts
  14. - **Minimal Dependencies**: Only requires `mcp>=2,<3` and Gemini CLI
  15. - **Easy Deployment**: Support for both uvx and traditional pip installation
  16. - **Universal MCP Compatibility**: Works with any MCP-compatible AI coding assistant
  17. - **Modern Python**: Uses pathlib and modern type hints (Python 3.10+)
  18. ## πŸš€ Quick Start
  19. ### Prerequisites
  20. 1. **Install Gemini CLI**:
  21. ```bash
  22. npm install -g @google/gemini-cli
  23. ```
  24. 2. **Authenticate with Gemini**:
  25. ```bash
  26. gemini auth login
  27. ```
  28. 3. **Verify installation**:
  29. ```bash
  30. gemini --version
  31. ```
  32. ### Installation
  33. **🎯 Recommended: PyPI Installation**
  34. ```bash
  35. # Install from PyPI
  36. pip install gemini-bridge
  37. # Add to Claude Code with uvx (recommended)
  38. claude mcp add gemini-bridge -s user -- uvx gemini-bridge
  39. ```
  40. **Alternative: From Source**
  41. ```bash
  42. # Clone the repository
  43. git clone https://github.com/shelakh/gemini-bridge.git
  44. cd gemini-bridge
  45. # Build and install locally
  46. uvx --from build pyproject-build
  47. pip install dist/*.whl
  48. # Add to Claude Code
  49. claude mcp add gemini-bridge -s user -- uvx gemini-bridge
  50. ```
  51. **Development Installation**
  52. ```bash
  53. # Clone and install in development mode
  54. git clone https://github.com/shelakh/gemini-bridge.git
  55. cd gemini-bridge
  56. pip install -e .
  57. # Add to Claude Code (development)
  58. claude mcp add gemini-bridge-dev -s user -- python -m src
  59. ```
  60. ## 🌐 Multi-Client Support
  61. **Gemini Bridge works with any MCP-compatible AI coding assistant** - the same server supports multiple clients through different configuration methods.
  62. ### Supported MCP Clients
  63. - **Claude Code** βœ… (Default)
  64. - **Cursor** βœ…
  65. - **VS Code** βœ…
  66. - **Windsurf** βœ…
  67. - **Cline** βœ…
  68. - **Void** βœ…
  69. - **Cherry Studio** βœ…
  70. - **Augment** βœ…
  71. - **Roo Code** βœ…
  72. - **Zencoder** βœ…
  73. - **Any MCP-compatible client** βœ…
  74. ### Configuration Examples
  75. <details>
  76. <summary><strong>Claude Code</strong> (Default)</summary>
  77. ```bash
  78. # Recommended installation
  79. claude mcp add gemini-bridge -s user -- uvx gemini-bridge
  80. # Development installation
  81. claude mcp add gemini-bridge-dev -s user -- python -m src
  82. ```
  83. </details>
  84. <details>
  85. <summary><strong>Cursor</strong></summary>
  86. **Global Configuration** (`~/.cursor/mcp.json`):
  87. ```json
  88. {
  89. "mcpServers": {
  90. "gemini-bridge": {
  91. "command": "uvx",
  92. "args": ["gemini-bridge"],
  93. "env": {}
  94. }
  95. }
  96. }
  97. ```
  98. **Project-Specific** (`.cursor/mcp.json` in your project):
  99. ```json
  100. {
  101. "mcpServers": {
  102. "gemini-bridge": {
  103. "command": "uvx",
  104. "args": ["gemini-bridge"],
  105. "env": {}
  106. }
  107. }
  108. }
  109. ```
  110. Go to: `Settings` β†’ `Cursor Settings` β†’ `MCP` β†’ `Add new global MCP server`
  111. </details>
  112. <details>
  113. <summary><strong>VS Code</strong></summary>
  114. **Configuration** (`.vscode/mcp.json` in your workspace):
  115. ```json
  116. {
  117. "servers": {
  118. "gemini-bridge": {
  119. "type": "stdio",
  120. "command": "uvx",
  121. "args": ["gemini-bridge"]
  122. }
  123. }
  124. }
  125. ```
  126. **Alternative: Through Extensions**
  127. 1. Open Extensions view (Ctrl+Shift+X)
  128. 2. Search for MCP extensions
  129. 3. Add custom server with command: `uvx gemini-bridge`
  130. </details>
  131. <details>
  132. <summary><strong>Windsurf</strong></summary>
  133. Add to your Windsurf MCP configuration:
  134. ```json
  135. {
  136. "mcpServers": {
  137. "gemini-bridge": {
  138. "command": "uvx",
  139. "args": ["gemini-bridge"],
  140. "env": {}
  141. }
  142. }
  143. }
  144. ```
  145. </details>
  146. <details>
  147. <summary><strong>Cline</strong> (VS Code Extension)</summary>
  148. 1. Open Cline and click **MCP Servers** in the top navigation
  149. 2. Select **Installed** tab β†’ **Advanced MCP Settings**
  150. 3. Add to `cline_mcp_settings.json`:
  151. ```json
  152. {
  153. "mcpServers": {
  154. "gemini-bridge": {
  155. "command": "uvx",
  156. "args": ["gemini-bridge"],
  157. "env": {}
  158. }
  159. }
  160. }
  161. ```
  162. </details>
  163. <details>
  164. <summary><strong>Void</strong></summary>
  165. Go to: `Settings` β†’ `MCP` β†’ `Add MCP Server`
  166. ```json
  167. {
  168. "mcpServers": {
  169. "gemini-bridge": {
  170. "command": "uvx",
  171. "args": ["gemini-bridge"],
  172. "env": {}
  173. }
  174. }
  175. }
  176. ```
  177. </details>
  178. <details>
  179. <summary><strong>Cherry Studio</strong></summary>
  180. 1. Navigate to **Settings β†’ MCP Servers β†’ Add Server**
  181. 2. Fill in the server details:
  182. - **Name**: `gemini-bridge`
  183. - **Type**: `STDIO`
  184. - **Command**: `uvx`
  185. - **Arguments**: `["gemini-bridge"]`
  186. 3. Save the configuration
  187. </details>
  188. <details>
  189. <summary><strong>Augment</strong></summary>
  190. **Using the UI:**
  191. 1. Click hamburger menu β†’ **Settings** β†’ **Tools**
  192. 2. Click **+ Add MCP** button
  193. 3. Enter command: `uvx gemini-bridge`
  194. 4. Name: **Gemini Bridge**
  195. **Manual Configuration:**
  196. ```json
  197. "augment.advanced": {
  198. "mcpServers": [
  199. {
  200. "name": "gemini-bridge",
  201. "command": "uvx",
  202. "args": ["gemini-bridge"],
  203. "env": {}
  204. }
  205. ]
  206. }
  207. ```
  208. </details>
  209. <details>
  210. <summary><strong>Roo Code</strong></summary>
  211. 1. Go to **Settings β†’ MCP Servers β†’ Edit Global Config**
  212. 2. Add to `mcp_settings.json`:
  213. ```json
  214. {
  215. "mcpServers": {
  216. "gemini-bridge": {
  217. "command": "uvx",
  218. "args": ["gemini-bridge"],
  219. "env": {}
  220. }
  221. }
  222. }
  223. ```
  224. </details>
  225. <details>
  226. <summary><strong>Zencoder</strong></summary>
  227. 1. Go to Zencoder menu (...) β†’ **Tools** β†’ **Add Custom MCP**
  228. 2. Add configuration:
  229. ```json
  230. {
  231. "command": "uvx",
  232. "args": ["gemini-bridge"],
  233. "env": {}
  234. }
  235. ```
  236. 3. Hit the **Install** button
  237. </details>
  238. <details>
  239. <summary><strong>Alternative Installation Methods</strong></summary>
  240. **For pip-based installations:**
  241. ```json
  242. {
  243. "command": "gemini-bridge",
  244. "args": [],
  245. "env": {}
  246. }
  247. ```
  248. **For development/local testing:**
  249. ```json
  250. {
  251. "command": "python",
  252. "args": ["-m", "src"],
  253. "env": {},
  254. "cwd": "/path/to/gemini-bridge"
  255. }
  256. ```
  257. **For npm-style installation** (if needed):
  258. ```json
  259. {
  260. "command": "npx",
  261. "args": ["gemini-bridge"],
  262. "env": {}
  263. }
  264. ```
  265. </details>
  266. ### Universal Usage
  267. Once configured with any client, use the same two tools:
  268. 1. **Ask general questions**: "What authentication patterns are used in this codebase?"
  269. 2. **Analyze specific files**: "Review these auth files for security issues"
  270. **The server implementation is identical** - only the client configuration differs!
  271. ## βš™οΈ Configuration
  272. ### Timeout Configuration
  273. By default, Gemini Bridge uses a 60-second timeout for all CLI operations. For longer queries (large files, complex analysis), you can configure a custom timeout using the `GEMINI_BRIDGE_TIMEOUT` environment variable.
  274. **Example configurations:**
  275. <details>
  276. <summary><strong>Claude Code</strong></summary>
  277. ```bash
  278. # Add with custom timeout (120 seconds)
  279. claude mcp add gemini-bridge -s user --env GEMINI_BRIDGE_TIMEOUT=120 -- uvx gemini-bridge
  280. ```
  281. </details>
  282. <details>
  283. <summary><strong>Manual Configuration (mcp_settings.json)</strong></summary>
  284. ```json
  285. {
  286. "mcpServers": {
  287. "gemini-bridge": {
  288. "command": "uvx",
  289. "args": ["gemini-bridge"],
  290. "env": {
  291. "GEMINI_BRIDGE_TIMEOUT": "120"
  292. }
  293. }
  294. }
  295. }
  296. ```
  297. </details>
  298. **Timeout Options:**
  299. - **Default**: 60 seconds (if not configured)
  300. - **Range**: Any positive integer (seconds)
  301. - **Per-call override**: Supply `timeout_seconds` to either tool for one-off extensions
  302. - **Recommended**: 120-300 seconds for large file analysis
  303. - **Invalid values**: Fall back to 60 seconds with warning
  304. ## πŸ› οΈ Available Tools
  305. ### `consult_gemini`
  306. Direct CLI bridge for simple queries.
  307. **Parameters:**
  308. - `query` (string): The question or prompt to send to Gemini
  309. - `directory` (string): Working directory for the query
  310. - `model` (string, optional): Model to use - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", or "auto" (default: "flash")
  311. - `timeout_seconds` (int, optional): Override the execution timeout for this request
  312. **Example:**
  313. ```python
  314. consult_gemini(
  315. query="Find authentication patterns in this codebase",
  316. directory="/path/to/project",
  317. model="flash"
  318. )
  319. ```
  320. ### `consult_gemini_with_files`
  321. CLI bridge with file attachments for detailed analysis.
  322. **Parameters:**
  323. - `query` (string): The question or prompt to send to Gemini
  324. - `directory` (string): Working directory for the query
  325. - `files` (list): List of file paths relative to the directory
  326. - `model` (string, optional): Model to use - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", or "auto" (default: "flash")
  327. - `timeout_seconds` (int, optional): Override the execution timeout for this request
  328. - `mode` (string, optional): Either `"inline"` (default) to stream file contents or `"at_command"` to let Gemini CLI resolve `@path` references itself
  329. **Example:**
  330. ```python
  331. consult_gemini_with_files(
  332. query="Analyze these auth files and suggest improvements",
  333. directory="/path/to/project",
  334. files=["src/auth.py", "src/models.py"],
  335. model="pro",
  336. timeout_seconds=180
  337. )
  338. ```
  339. **Tip:** When scanning large trees, switch to `mode="at_command"` so the Gemini CLI handles file globbing and truncation natively.
  340. ### `web_search`
  341. Ask Gemini queries with web search context. Uses Gemini CLI's automatic web search when the model determines it's needed. Best-effort functionality - not guaranteed for every query.
  342. **Parameters:**
  343. - `query` (string): Search query or question to look up on the web
  344. - `directory` (string): Working directory for command execution
  345. - `model` (string, optional): Model to use - "flash", "pro", "flash-lite", "2.5-lite", "3-pro", "3-flash", "3.1-pro", "3.1-flash-lite", or "auto" (default: "flash")
  346. - `timeout_seconds` (int, optional): Override the execution timeout for this request
  347. **Example:**
  348. ```python
  349. web_search(
  350. query="latest Python version and new features",
  351. model="flash"
  352. )
  353. ```
  354. ## πŸ“‹ Usage Examples
  355. ### Basic Code Analysis
  356. ```python
  357. # Simple research query
  358. consult_gemini(
  359. query="What authentication patterns are used in this project?",
  360. directory="/Users/dev/my-project"
  361. )
  362. ```
  363. ### Detailed File Review
  364. ```python
  365. # Analyze specific files
  366. consult_gemini_with_files(
  367. query="Review these files and suggest security improvements",
  368. directory="/Users/dev/my-project",
  369. files=["src/auth.py", "src/middleware.py"],
  370. model="pro"
  371. )
  372. ```
  373. ### Multi-file Analysis
  374. ```python
  375. # Compare multiple implementation files
  376. consult_gemini_with_files(
  377. query="Compare these database implementations and recommend the best approach",
  378. directory="/Users/dev/my-project",
  379. files=["src/db/postgres.py", "src/db/sqlite.py", "src/db/redis.py"],
  380. mode="at_command"
  381. )
  382. ```
  383. ### Web Search
  384. ```python
  385. # Get current information from the web
  386. web_search(
  387. query="latest Python version and new features in 3.13",
  388. model="flash"
  389. )
  390. ```
  391. ### Large File Safeguards
  392. - Inline transfers cap at ~256 KB per file and ~512 KB per request to avoid hangs.
  393. - Oversized files are truncated to head/tail snippets with a warning in the MCP response.
  394. - Tune the caps with environment variables (`GEMINI_BRIDGE_MAX_INLINE_TOTAL_BYTES`, etc.) or prefer `mode="at_command"` for bigger payloads.
  395. ## πŸ—οΈ Architecture
  396. ### Core Design
  397. - **CLI-First**: Direct subprocess calls to `gemini` command
  398. - **Stateless**: Each tool call is independent with no session state
  399. - **Adaptive Timeout**: Defaults to 60 seconds but overridable per request or via env var
  400. - **Attachment Guardrails**: Inline mode enforces lightweight limits; `@` mode delegates to Gemini CLI tooling
  401. - **Simple Error Handling**: Clear error messages with fail-fast approach
  402. ### Project Structure
  403. ```
  404. gemini-bridge/
  405. β”œβ”€β”€ src/
  406. β”‚ β”œβ”€β”€ __init__.py # Entry point
  407. β”‚ β”œβ”€β”€ __main__.py # Module execution entry point
  408. β”‚ └── mcp_server.py # Main MCP server implementation
  409. β”œβ”€β”€ .github/ # GitHub templates and workflows
  410. β”œβ”€β”€ pyproject.toml # Python package configuration
  411. β”œβ”€β”€ README.md # This file
  412. β”œβ”€β”€ CONTRIBUTING.md # Contribution guidelines
  413. β”œβ”€β”€ CODE_OF_CONDUCT.md # Community standards
  414. β”œβ”€β”€ SECURITY.md # Security policies
  415. β”œβ”€β”€ CHANGELOG.md # Version history
  416. └── LICENSE # MIT license
  417. ```
  418. ## πŸ”§ Development
  419. ### Local Testing
  420. ```bash
  421. # Install in development mode
  422. pip install -e .
  423. # Run directly
  424. python -m src
  425. # Test CLI availability
  426. gemini --version
  427. ```
  428. ### Integration with Claude Code
  429. The server automatically integrates with Claude Code when properly configured through the MCP protocol.
  430. ## πŸ” Troubleshooting
  431. ### CLI Not Available
  432. ```bash
  433. # Install Gemini CLI
  434. npm install -g @google/gemini-cli
  435. # Authenticate
  436. gemini auth login
  437. # Test
  438. gemini --version
  439. ```
  440. ### Connection Issues
  441. - Verify Gemini CLI is properly authenticated
  442. - Check network connectivity
  443. - Ensure Claude Code MCP configuration is correct
  444. - Check that the `gemini` command is in your PATH
  445. ### Common Error Messages
  446. - **"CLI not available"**: Gemini CLI is not installed or not in PATH
  447. - **"Authentication required"**: Run `gemini auth login`
  448. - **"Timeout after 60 seconds"**: Query took too long, try breaking it into smaller parts
  449. ## 🀝 Contributing
  450. We welcome contributions from the community! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started.
  451. ### Quick Contributing Guide
  452. 1. Fork the repository
  453. 2. Create a feature branch
  454. 3. Make your changes
  455. 4. Add tests if applicable
  456. 5. Submit a pull request
  457. ## πŸ“„ License
  458. This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
  459. ## πŸ”„ Version History
  460. See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
  461. ## πŸ†˜ Support
  462. - **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/shelakh/gemini-bridge/issues)
  463. - **Discussions**: Join the community discussion
  464. - **Documentation**: Additional docs can be created in the `docs/` directory
  465. ---
  466. **Focus**: A simple, reliable bridge between Claude Code and Gemini AI through the official CLI.

Ratings and comments

Sign in to rate this skill.

Sign in

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