Skip to content
Back to search

claude-gemini-mcp-slim

Lightweight MCP integration bringing Google's Gemini AI capabilities to Claude Code with 1M+ token context window, smart model selection, and powerful code analysis tools

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/cmdaltctr--claude-gemini-mcp-slim/badge.svg)](/listings/cmdaltctr--claude-gemini-mcp-slim)

HTML

<a href="/listings/cmdaltctr--claude-gemini-mcp-slim"><img src="/api/listings/cmdaltctr--claude-gemini-mcp-slim/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.

To set up a local development environment for this MCP server:

Quick Setup (Recommended)

# Clone the repository
git clone https://github.com/yourusername/claude-gemini-mcp-slim.git
cd claude-gemini-mcp-slim

# Run the automated setup script
./setup-dev.sh

The setup script will: - Create a Python virtual environment (`.venv`) - Install all production and development dependencies - Set up unified Husky hooks for code quality and commit validation - Run a quick test to verify everything is working

Manual Setup

If you prefer to set up manually:

# Create virtual environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-dev.txt

# Set up unified Husky hooks (handled by setup-dev.sh)
# This includes pre-commit formatting/linting and commit-msg validation

# Run tests
python -m pytest

Development Workflow

Once set up, your typical development workflow will be:

# Activate virtual environment
source .venv/bin/activate

# Make your changes
# ...

# Run tests
python -m pytest

# Run Husky hooks manually (optional, they run automatically on commit)
.husky/pre-commit  # Run formatting, linting, and tests
.husky/commit-msg  # Validate commit message format

# Commit changes (pre-commit hooks will run automatically)
git add .
git commit -m "Your commit message"

**Important Notes:** - The virtual environment (`.venv`) is automatically ignored by git - Husky hooks will run automatically on every commit to ensure code quality and enforce conventional commit messages - If you're using an IDE like Windsurf, make sure it's configured to use the virtual environment

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 · 404 lines

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

  1. # Claude Gemini MCP Integration
  2. <!-- CI workflow trigger -->
  3. ![Version](https://img.shields.io/badge/version-1.3.1-blue.svg)
  4. ![Security](https://img.shields.io/badge/security-hardened-green.svg)
  5. ![License](https://img.shields.io/badge/license-MIT-blue.svg)
  6. ![Python](https://img.shields.io/badge/python-3.10+-brightgreen.svg)
  7. ![Status](https://img.shields.io/badge/status-production%20ready-green.svg)
  8. ![Slash Commands](https://img.shields.io/badge/slash%20commands-20+-orange.svg)
  9. > **🚀 What's Coming Next:**
  10. > I'm building an **AI Agent Feedback Loop System** that enables intelligent collaboration between Claude Code and Gemini AI. This will create a continuous improvement cycle where both AI agents learn from each other's suggestions, creating smarter code analysis and more contextual development assistance. Starting with Claude Code, then expanding to other IDEs. Stay tuned!
  11. **A lightweight integration that brings Google's Gemini AI capabilities to Claude Code through MCP (Model Context Protocol)**
  12. This project connects Claude Code (your coding assistant) with Google's Gemini AI models. Think of it as adding a second AI expert to your development team - one that can read and understand massive amounts of code at once (1M+ tokens, which is like reading hundreds of code files simultaneously).
  13. With this integration, you can ask Gemini questions about your code, get security reviews, performance suggestions, and architectural advice - all without leaving your coding environment. It automatically chooses the right AI model for each task: fast responses for quick questions, deeper analysis for complex problems.
  14. ## Table of Contents
  15. - [Key Features](#key-features)
  16. - [How It Works](#how-it-works)
  17. - [Architecture Overview](#architecture-overview)
  18. - [Key Benefits](#key-benefits)
  19. - [File Structure](#file-structure)
  20. - [Project Structure](#project-structure-with-hooks-enabled)
  21. - [Multi-Client Support](#multi-client-support)
  22. - [Quick Start](#quick-start)
  23. - [Usage Examples](#usage-examples)
  24. - [Quick Development Questions](#quick-development-questions)
  25. - [Code Analysis](#code-analysis)
  26. - [Full Project Analysis](#full-project-analysis)
  27. - [Automated Hooks System](#automated-hooks-system)
  28. - [Benefits](#benefits)
  29. - [For Developers](#for-developers)
  30. - [For Code Quality](#for-code-quality)
  31. - [For Productivity](#for-productivity)
  32. - [Usage Examples with Slash Commands](#usage-examples-with-slash-commands)
  33. - [What's Next?](#whats-next)
  34. - [Need Help?](#need-help)
  35. - [Further Documentation](#further-documentation)
  36. - [Changelog](#changelog)
  37. - [Contributing](#contributing)
  38. - [License](#license)
  39. - [Credits](#credits)
  40. ## Key Features
  41. - **Quick Query** - Ask Gemini any development question instantly
  42. - **Code Analysis** - Deep analysis with security, performance, and architecture insights
  43. - **Codebase Analysis** - Full project analysis using Gemini's massive context window
  44. - **Automated Hooks** - Pre-edit analysis, pre-commit review, and session summaries
  45. - **20+ Slash Commands** - Simple shortcuts like `/g`, `/analyze`, `/security`
  46. - **Smart Model Selection** - Flash for speed, Pro for depth, automatic fallback
  47. - **Real-time Streaming** - Live output with progress indicators
  48. ## How It Works
  49. ```
  50. Claude Code ←→ MCP Server ←→ Gemini CLI/API ←→ Google Gemini Models
  51. ↓
  52. Smart Model Selection
  53. (Flash for speed, Pro for depth)
  54. ```
  55. ## Architecture Overview
  56. The Gemini MCP server uses a shared architecture where one installation serves multiple AI clients and projects:
  57. ```
  58. Claude Desktop │ Claude Code │ Cursor IDE │ VS Code + Extensions
  59. │ │ │
  60. └──────────────┼─────────────┘
  61. │
  62. ┌─────────────────────────┐
  63. │ MCP Protocol │
  64. │ (Tool Requests) │
  65. └─────────────────────────┘
  66. │
  67. ┌─────────────────┐
  68. │ Gemini MCP │
  69. │ Server │
  70. │ (Python/Shell) │
  71. └─────────────────┘
  72. │
  73. ┌───────────────┼───────────────┐
  74. │ │ │
  75. ┌─────────────────┐ ┌─────────────────┐ │
  76. │ Gemini API │ │ Gemini CLI │ │
  77. │ (Direct HTTP) │ │ (Shell Command)│ │
  78. └─────────────────┘ └─────────────────┘ │
  79. │ │ │
  80. └───────────────┼───────────────┘
  81. │
  82. ┌─────────────────────────┐
  83. │ Google Gemini AI │
  84. │ (1M+ Token Context) │
  85. └─────────────────────────┘
  86. ```
  87. ### Key Benefits
  88. - **One installation** serves all AI clients and projects
  89. - **No project pollution** - keeps your projects clean
  90. - **Easy maintenance** - update once, benefits everywhere
  91. - **Smart fallbacks** - API-first approach with CLI backup
  92. ### File Structure
  93. ```
  94. ~/mcp-servers/ ← Central location for all MCP servers
  95. ├── shared-mcp-env/ ← Shared virtual environment
  96. │ ├── bin/python ← Python interpreter for all MCPs
  97. │ └── lib/python3.x/site-packages/ ← Shared dependencies (mcp, google-generativeai, etc.)
  98. └── gemini-mcp/ ← Complete Gemini MCP package
  99. ├── gemini_mcp_server.py ← Main MCP server
  100. └── .claude/ ← Complete slash commands system
  101. ├── hooks.json ← Hook definitions
  102. ├── commands/ ← Native slash commands (10+ commands)
  103. │ ├── gemini.md ← /gemini command
  104. │ ├── analyze.md ← /analyze command
  105. │ └── ... ← Other command definitions
  106. └── scripts/
  107. └── slim_gemini_hook.py ← Hook execution script
  108. ```
  109. ### Project Structure (with hooks enabled)
  110. ```
  111. your-project/
  112. ├── .claude → ~/mcp-servers/gemini-mcp/.claude ← Symlink to shared hooks
  113. ├── src/ ← Your project files
  114. ├── README.md
  115. └── (no venv or MCP files needed!) ← Clean project structure
  116. ```
  117. ### Multi-Client Support
  118. The shared MCP architecture supports multiple AI clients simultaneously:
  119. **Supported Clients:**
  120. - Claude Desktop - Core MCP tools only
  121. - Claude Code - Core MCP tools + hooks (if configured)
  122. - VS Code with Claude Code extension - Core MCP tools + hooks (if configured)
  123. - Cursor IDE - Core MCP tools only
  124. - Windsurf - Core MCP tools only
  125. - VS Code with other MCP extensions - Core MCP tools only
  126. - Any MCP-compatible client - Core MCP tools only
  127. **Important:** Hook functionality (.claude/hooks.json) is exclusive to Claude Code ecosystem (Claude Code standalone + VS Code with Claude Code extension). No other AI client currently supports this automation system.
  128. ## Quick Start
  129. **New to this project?** Here's what you need to do:
  130. 1. **Get your Google API key** from [Google AI Studio](https://makersuite.google.com/)
  131. 2. **Follow the complete setup guide** in [docs/SETUP/SETUP.md](docs/SETUP/SETUP.md)
  132. 3. **Test the integration** with a simple query
  133. 4. **Explore the 20+ slash commands** in [docs/README-SLASH-COMMANDS.md](docs/README-SLASH-COMMANDS.md)
  134. **Installation time:** ~5 minutes | **Prerequisites:** Python 3.10+, Node.js 16+
  135. ## Usage Examples
  136. ### Quick Development Questions
  137. ```
  138. Use gemini_quick_query for:
  139. - "How do I implement JWT authentication in Node.js?"
  140. - "What's the difference between useEffect and useLayoutEffect?"
  141. - "Best practices for error handling in Python async functions"
  142. ```
  143. ### Code Analysis
  144. ```
  145. Use gemini_analyze_code for:
  146. - Security review of authentication functions
  147. - Performance analysis of database queries
  148. - Architecture review before major refactoring
  149. ```
  150. ### Full Project Analysis
  151. ```
  152. Use gemini_codebase_analysis for:
  153. - Overall architecture assessment
  154. - Security vulnerability scanning
  155. - Performance bottleneck identification
  156. ```
  157. ### Automated Hooks System
  158. ```
  159. The hooks system provides intelligent automation that runs at key development moments:
  160. Pre-edit Analysis:
  161. - Automatically analyzes files before Claude Code edits them
  162. - Provides context about security, performance, and architecture concerns
  163. - Helps prevent issues by informing Claude Code before changes are made
  164. Pre-commit Review:
  165. - Analyzes staged changes before git commits
  166. - Reviews code for critical bugs, security vulnerabilities, and quality issues
  167. - Provides final quality check before code enters version control
  168. Session Summary:
  169. - Generates brief recap when Claude Code session ends
  170. - Highlights key changes made and potential next steps
  171. - Maintains development context between sessions
  172. ```
  173. ## Benefits
  174. ### For Developers
  175. - **Instant access** to Gemini's advanced AI capabilities
  176. - **Seamless integration** within Claude Code workflow
  177. - **Smart model selection** - fast responses when speed matters, deep analysis when needed
  178. - **Real-time feedback** during long analysis tasks
  179. ### For Code Quality
  180. - **Security analysis** using Gemini's latest training data
  181. - **Performance insights** from large-scale pattern recognition
  182. - **Architecture guidance** based on current best practices
  183. - **Error prevention** through pre-edit analysis
  184. ### For Productivity
  185. - **Reduced context switching** - stay in Claude Code
  186. - **Faster debugging** with AI-powered error analysis
  187. - **Better decisions** through comprehensive code review
  188. - **Learning acceleration** via instant expert guidance
  189. ## Usage Examples with Slash Commands
  190. The slash commands provide a much simpler way to access Gemini's powerful analysis without remembering the full MCP tool syntax:
  191. ```
  192. # Instead of typing:
  193. /mcp__gemini-mcp__gemini_quick_query "How do I implement JWT authentication in Node.js?"
  194. # You can simply use:
  195. /gemini How do I implement JWT authentication in Node.js?
  196. # or even shorter:
  197. /g How do I implement JWT authentication in Node.js?
  198. ```
  199. ```
  200. # Instead of typing:
  201. /mcp__gemini-mcp__gemini_codebase_analysis "./src" security
  202. # You can simply use:
  203. /codebase ./src security
  204. # or even shorter:
  205. /c ./src security
  206. ```
  207. See [docs/README-SLASH-COMMANDS.md](docs/README-SLASH-COMMANDS.md) for all available shortcuts.
  208. ## What's Next?
  209. Once everything is working:
  210. 1. **Try the tools** - Start with simple queries: `/mcp__gemini-mcp__gemini_quick_query "How do I optimize React performance?"`
  211. 2. **Analyze some code** - Analyze specific functions: `/mcp__gemini-mcp__gemini_analyze_code "your function code here" security`
  212. 3. **Review your project** - Get architectural insights: `/mcp__gemini-mcp__gemini_codebase_analysis "./src" architecture`
  213. 4. **Explore slash commands** - Check `docs/README-SLASH-COMMANDS.md` for 20+ shortcuts
  214. ## Need Help?
  215. - **Submit an Issue:** If you encounter any problems, please submit an issue on our [GitHub repository](https://github.com/cmdaltctr/claude-gemini-mcp-slim/issues) with details about your environment, steps to reproduce, and any error messages you received.
  216. - **Use Labels:** When submitting issues, please use appropriate labels/tags such as `bug`, `feature-request`, `documentation`, and so on ([available labels](https://github.com/cmdaltctr/claude-gemini-mcp-slim/labels)) to help us categorize and address your concerns more efficiently.
  217. - **Test files:** Check the `tests/` folder for examples and testing scripts
  218. - **Slash commands:** See `docs/README-SLASH-COMMANDS.md` for comprehensive command reference
  219. - **Console Logs:** Check your Claude Desktop/Code console for detailed error messages that can help diagnose issues
  220. ## Further Documentation
  221. - [docs/SETUP/SETUP.md](docs/SETUP/SETUP.md) - Complete installation and configuration guide
  222. - [docs/README-SLASH-COMMANDS.md](docs/README-SLASH-COMMANDS.md) - Slash commands reference
  223. - [docs/SECURITY.md](docs/SECURITY.md) - Security documentation and hardening details
  224. - [docs/TESTING.md](docs/TESTING.md) - Testing guide and best practices
  225. ## Changelog
  226. **📋 Complete Changelog:** For detailed release notes and full version history, see [docs/CHANGELOG.md](docs/CHANGELOG.md)
  227. ## Contributing
  228. This project is designed to be lightweight and focused. The core functionality is complete, but contributions are welcome for:
  229. - Additional analysis types
  230. - Better error handling
  231. - Performance optimizations
  232. - Documentation improvements
  233. ### How to Contribute
  234. 1. **Fork the repository**
  235. 2. **Create a feature branch**: `git checkout -b feature/your-feature-name`
  236. 3. **Make your changes**: Implement your feature or bug fix
  237. 4. **Test with MCP integration**: Ensure your changes work with this repo's MCP server
  238. 5. **Submit a pull request**: Push to your fork and submit a PR to the main repository
  239. ### Development Guidelines
  240. - **Clean Python Code**: Use type hints, docstrings, and follow the existing code structure
  241. - **Security-First Approach**: Implement proper input sanitization and API key protection
  242. - **Modular Design**: Keep functions focused and reusable with clear error handling
  243. - **MCP Protocol Compliance**: Follow the MCP server specifications for all tools
  244. - **Comprehensive Documentation**: Document all tools with clear descriptions and schemas
  245. - **Concise Code Comments**: Add brief comments to explain code blocks' purpose and functionality
  246. - **Fallback Mechanisms**: Implement API with CLI fallbacks for resilience
  247. - **Testing**: Verify changes work with both direct API and CLI integrations
  248. ### Development Setup
  249. To set up a local development environment for this MCP server:
  250. #### Quick Setup (Recommended)
  251. ```bash
  252. # Clone the repository
  253. git clone https://github.com/yourusername/claude-gemini-mcp-slim.git
  254. cd claude-gemini-mcp-slim
  255. # Run the automated setup script
  256. ./setup-dev.sh
  257. ```
  258. The setup script will:
  259. - Create a Python virtual environment (`.venv`)
  260. - Install all production and development dependencies
  261. - Set up unified Husky hooks for code quality and commit validation
  262. - Run a quick test to verify everything is working
  263. #### Manual Setup
  264. If you prefer to set up manually:
  265. ```bash
  266. # Create virtual environment
  267. python3 -m venv .venv
  268. source .venv/bin/activate
  269. # Install dependencies
  270. pip install -r requirements.txt
  271. pip install -r requirements-dev.txt
  272. # Set up unified Husky hooks (handled by setup-dev.sh)
  273. # This includes pre-commit formatting/linting and commit-msg validation
  274. # Run tests
  275. python -m pytest
  276. ```
  277. #### Development Workflow
  278. Once set up, your typical development workflow will be:
  279. ```bash
  280. # Activate virtual environment
  281. source .venv/bin/activate
  282. # Make your changes
  283. # ...
  284. # Run tests
  285. python -m pytest
  286. # Run Husky hooks manually (optional, they run automatically on commit)
  287. .husky/pre-commit # Run formatting, linting, and tests
  288. .husky/commit-msg # Validate commit message format
  289. # Commit changes (pre-commit hooks will run automatically)
  290. git add .
  291. git commit -m "Your commit message"
  292. ```
  293. **Important Notes:**
  294. - The virtual environment (`.venv`) is automatically ignored by git
  295. - Husky hooks will run automatically on every commit to ensure code quality and enforce conventional commit messages
  296. - If you're using an IDE like Windsurf, make sure it's configured to use the virtual environment
  297. ## License
  298. MIT License
  299. Copyright (c) 2025 Dr Muhammad Aizat Hawari
  300. This project is licensed under the MIT License - see the [LICENSE.md](LICENSE.md) file for details.
  301. ---
  302. ## Credits
  303. Special thanks to the following tools and platforms that assisted during the research and development of this MCP:
  304. - **[Claude](https://claude.ai/)** - AI assistant for code development and documentation
  305. - **[Perplexity](https://www.perplexity.ai/)** - AI-powered research and information gathering
  306. - **[Warp Terminal](https://www.warp.dev/)** - Modern terminal for enhanced development workflow

Ratings and comments

Sign in to rate this skill.

Sign in

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