Content
# Gemini MCP Server
[](https://smithery.ai/server/mcp-server-gemini)
[](https://www.npmjs.com/package/mcp-server-gemini)
[](https://opensource.org/licenses/MIT)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
A powerful MCP (Model Context Protocol) server that brings Google's latest Gemini AI models to your favorite development environment. Access Gemini 2.5's thinking capabilities, vision analysis, embeddings, and more through a seamless integration.
🚀 **Works with**: Claude Desktop, Cursor, Windsurf, and any MCP-compatible client
🎯 **Why use this**: Get Gemini's cutting-edge AI features directly in your IDE with full parameter control
📚 **Self-documenting**: Built-in help system means you never need to leave your editor
## Features
- **6 Powerful Tools**: Text generation, image analysis, token counting, model listing, embeddings, and self-documenting help
- **Latest Gemini Models**: Support for Gemini 2.5 series with thinking capabilities
- **Advanced Features**: JSON mode, Google Search grounding, system instructions, conversation memory
- **Full MCP Protocol**: Standard stdio communication for seamless integration with any MCP client
- **Self-Documenting**: Built-in help system - no external docs needed
- **TypeScript & ESM**: Modern, type-safe implementation
### Supported Models
| Model | Context | Features | Best For |
|-------|---------|----------|----------|
| gemini-2.5-pro | 2M tokens | Thinking, JSON, Grounding | Complex reasoning |
| gemini-2.5-flash ⭐ | 1M tokens | Thinking, JSON, Grounding | General use |
| gemini-2.5-flash-lite | 1M tokens | Thinking, JSON | Fast responses |
| gemini-2.0-flash | 1M tokens | JSON, Grounding | Standard tasks |
| gemini-1.5-pro | 2M tokens | JSON | Legacy support |
## Quick Start
1. **Get Gemini API Key**
- Visit [Google AI Studio](https://makersuite.google.com/app/apikey)
- Create a new API key
- **IMPORTANT**: Keep your API key secure and never commit it to version control
2. **Configure Your MCP Client**
<details>
<summary><b>Claude Desktop</b></summary>
Config location:
- Mac: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"gemini": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:aliargun/mcp-server-gemini"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}
```
</details>
<details>
<summary><b>Cursor</b></summary>
Add to Cursor's MCP settings:
```json
{
"gemini": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:aliargun/mcp-server-gemini"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
```
</details>
<details>
<summary><b>Windsurf</b></summary>
Configure in Windsurf's MCP settings following their documentation.
</details>
<details>
<summary><b>Other MCP Clients</b></summary>
Use the standard MCP stdio configuration:
```json
{
"type": "stdio",
"command": "npx",
"args": ["-y", "github:aliargun/mcp-server-gemini"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
```
</details>
3. **Restart Your MCP Client**
## How to Use
Once configured, you can use natural language in your MCP client to access Gemini's capabilities:
### Basic Commands
```
"Use Gemini to explain quantum computing"
"Analyze this image with Gemini"
"List all Gemini models"
"Get help on using Gemini"
```
### Advanced Examples
```
"Use Gemini 2.5 Pro with temperature 0.3 to review this code"
"Use Gemini in JSON mode to extract key points with schema {title, summary, tags}"
"Use Gemini with grounding to research the latest in quantum computing"
```
📖 **[See the complete Usage Guide](USAGE_GUIDE.md)** for detailed examples and advanced features.
## Why Gemini MCP Server?
- **Access Latest Models**: Use Gemini 2.5 with thinking capabilities - Google's most advanced models
- **Full Feature Set**: All Gemini API features including JSON mode, grounding, and system instructions
- **Easy Setup**: One-line npx installation, no complex configuration needed
- **Production Ready**: Comprehensive error handling, TypeScript types, and extensive documentation
- **Active Development**: Regular updates with new Gemini features as they're released
## Documentation
- **[Usage Guide](USAGE_GUIDE.md)** - Complete guide on using all tools and features
- **[Parameters Reference](PARAMETERS_REFERENCE.md)** - Detailed documentation of all parameters
- **[Quick Reference](QUICK_REFERENCE.md)** - Quick commands cheat sheet
- **[Enhanced Features](ENHANCED_FEATURES.md)** - Detailed list of v4.0.0 capabilities
- [Claude Desktop Setup Guide](docs/claude-desktop-setup.md) - Detailed setup instructions
- [Examples and Usage](docs/examples.md) - Usage examples and advanced configuration
- [Implementation Notes](docs/implementation-notes.md) - Technical implementation details
- [Development Guide](docs/development-guide.md) - Guide for developers
- [Troubleshooting Guide](docs/troubleshooting.md) - Common issues and solutions
## Local Development
```bash
# Clone repository
git clone https://github.com/aliargun/mcp-server-gemini.git
cd mcp-server-gemini
# Install dependencies
npm install
# Set up environment variables
cp .env.example .env
# Edit .env and add your GEMINI_API_KEY
# Start development server
npm run dev
```
## Contributing
Contributions are welcome! Please see our [Contributing Guide](CONTRIBUTING.md).
## Common Issues
1. **Connection Issues**
- Ensure your MCP client is properly restarted
- Check the client's logs (e.g., `~/Library/Logs/Claude/mcp-server-gemini.log` for Claude Desktop on Mac)
- Verify internet connection
- See [Troubleshooting Guide](docs/troubleshooting.md)
2. **API Key Problems**
- Verify API key is correct
- Check API key has proper permissions
- Ensure the key is set in the environment variable
- See [Setup Guide](docs/claude-desktop-setup.md)
## Security
- API keys are handled via environment variables only
- Never commit API keys to version control
- The `.claude/` directory is excluded from git
- No sensitive data is logged or stored
- Regular security updates
- If your API key is exposed, regenerate it immediately in Google Cloud Console
## License
MIT
