| Name | gemini-bridge JSON |
| Version |
1.0.1
JSON |
| download |
| home_page | None |
| Summary | Lightweight MCP server bridging Claude Code to Google's Gemini AI via official CLI |
| upload_time | 2025-08-25 16:08:22 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | None |
| keywords |
mcp
gemini
ai
coding
assistant
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Gemini Bridge
A lightweight MCP (Model Context Protocol) server that enables Claude Code to interact with Google's Gemini AI through the official CLI. Designed for simplicity, reliability, and seamless integration.
## ✨ Features
- **Direct Gemini CLI Integration**: Zero API costs using official Gemini CLI
- **Simple MCP Tools**: Two core functions for basic queries and file analysis
- **Stateless Operation**: No sessions, caching, or complex state management
- **Production Ready**: Robust error handling with configurable 60-second timeouts
- **Minimal Dependencies**: Only requires `mcp>=1.0.0` and Gemini CLI
- **Easy Deployment**: Support for both uvx and traditional pip installation
## 🚀 Quick Start
### Prerequisites
1. **Install Gemini CLI**:
```bash
npm install -g @google/gemini-cli
```
2. **Authenticate with Gemini**:
```bash
gemini auth login
```
3. **Verify installation**:
```bash
gemini --version
```
### Installation
**🎯 Recommended: PyPI Installation**
```bash
# 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**
```bash
# 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**
```bash
# 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
```
## 🛠️ Available Tools
### `consult_gemini`
Direct CLI bridge for simple queries.
**Parameters:**
- `query` (string): The question or prompt to send to Gemini
- `directory` (string): Working directory for the query (default: current directory)
- `model` (string, optional): Model to use - "flash" or "pro" (default: "flash")
**Example:**
```python
consult_gemini(
query="Find authentication patterns in this codebase",
directory="/path/to/project",
model="flash"
)
```
### `consult_gemini_with_files`
CLI bridge with file attachments for detailed analysis.
**Parameters:**
- `query` (string): The question or prompt to send to Gemini
- `directory` (string): Working directory for the query
- `files` (list): List of file paths relative to the directory
- `model` (string, optional): Model to use - "flash" or "pro" (default: "flash")
**Example:**
```python
consult_gemini_with_files(
query="Analyze these auth files and suggest improvements",
directory="/path/to/project",
files=["src/auth.py", "src/models.py"],
model="pro"
)
```
## 📋 Usage Examples
### Basic Code Analysis
```python
# Simple research query
consult_gemini(
query="What authentication patterns are used in this project?",
directory="/Users/dev/my-project"
)
```
### Detailed File Review
```python
# Analyze specific files
consult_gemini_with_files(
query="Review these files and suggest security improvements",
directory="/Users/dev/my-project",
files=["src/auth.py", "src/middleware.py"],
model="pro"
)
```
### Multi-file Analysis
```python
# Compare multiple implementation files
consult_gemini_with_files(
query="Compare these database implementations and recommend the best approach",
directory="/Users/dev/my-project",
files=["src/db/postgres.py", "src/db/sqlite.py", "src/db/redis.py"]
)
```
## 🏗️ Architecture
### Core Design
- **CLI-First**: Direct subprocess calls to `gemini` command
- **Stateless**: Each tool call is independent with no session state
- **Fixed Timeout**: 60-second maximum execution time
- **Simple Error Handling**: Clear error messages with fail-fast approach
### Project Structure
```
gemini-bridge/
├── src/
│ ├── __init__.py # Entry point
│ ├── __main__.py # Module execution entry point
│ └── mcp_server.py # Main MCP server implementation
├── .github/ # GitHub templates and workflows
├── pyproject.toml # Python package configuration
├── README.md # This file
├── CONTRIBUTING.md # Contribution guidelines
├── CODE_OF_CONDUCT.md # Community standards
├── SECURITY.md # Security policies
├── CHANGELOG.md # Version history
└── LICENSE # MIT license
```
## 🔧 Development
### Local Testing
```bash
# Install in development mode
pip install -e .
# Run directly
python -m src
# Test CLI availability
gemini --version
```
### Integration with Claude Code
The server automatically integrates with Claude Code when properly configured through the MCP protocol.
## 🔍 Troubleshooting
### CLI Not Available
```bash
# Install Gemini CLI
npm install -g @google/gemini-cli
# Authenticate
gemini auth login
# Test
gemini --version
```
### Connection Issues
- Verify Gemini CLI is properly authenticated
- Check network connectivity
- Ensure Claude Code MCP configuration is correct
- Check that the `gemini` command is in your PATH
### Common Error Messages
- **"CLI not available"**: Gemini CLI is not installed or not in PATH
- **"Authentication required"**: Run `gemini auth login`
- **"Timeout after 60 seconds"**: Query took too long, try breaking it into smaller parts
## 🤝 Contributing
We welcome contributions from the community! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started.
### Quick Contributing Guide
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🔄 Version History
See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
## 🆘 Support
- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/shelakh/gemini-bridge/issues)
- **Discussions**: Join the community discussion
- **Documentation**: Additional docs can be created in the `docs/` directory
---
**Focus**: A simple, reliable bridge between Claude Code and Gemini AI through the official CLI.
Raw data
{
"_id": null,
"home_page": null,
"name": "gemini-bridge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, gemini, ai, coding, assistant",
"author": null,
"author_email": "Shelakh <info@shelakh.com>",
"download_url": "https://files.pythonhosted.org/packages/99/df/a47ad5ad9d9072bf79b9b46eb1c51c4dcaeb001329c7409ad5438e154bf5/gemini_bridge-1.0.1.tar.gz",
"platform": null,
"description": "# Gemini Bridge\n\n\n\n\n\n\nA lightweight MCP (Model Context Protocol) server that enables Claude Code to interact with Google's Gemini AI through the official CLI. Designed for simplicity, reliability, and seamless integration.\n\n## \u2728 Features\n\n- **Direct Gemini CLI Integration**: Zero API costs using official Gemini CLI\n- **Simple MCP Tools**: Two core functions for basic queries and file analysis\n- **Stateless Operation**: No sessions, caching, or complex state management\n- **Production Ready**: Robust error handling with configurable 60-second timeouts\n- **Minimal Dependencies**: Only requires `mcp>=1.0.0` and Gemini CLI\n- **Easy Deployment**: Support for both uvx and traditional pip installation\n\n## \ud83d\ude80 Quick Start\n\n### Prerequisites\n\n1. **Install Gemini CLI**:\n ```bash\n npm install -g @google/gemini-cli\n ```\n\n2. **Authenticate with Gemini**:\n ```bash\n gemini auth login\n ```\n\n3. **Verify installation**:\n ```bash\n gemini --version\n ```\n\n### Installation\n\n**\ud83c\udfaf Recommended: PyPI Installation**\n```bash\n# Install from PyPI\npip install gemini-bridge\n\n# Add to Claude Code with uvx (recommended)\nclaude mcp add gemini-bridge -s user -- uvx gemini-bridge\n```\n\n**Alternative: From Source**\n```bash\n# Clone the repository\ngit clone https://github.com/shelakh/gemini-bridge.git\ncd gemini-bridge\n\n# Build and install locally\nuvx --from build pyproject-build\npip install dist/*.whl\n\n# Add to Claude Code\nclaude mcp add gemini-bridge -s user -- uvx gemini-bridge\n```\n\n**Development Installation**\n```bash\n# Clone and install in development mode\ngit clone https://github.com/shelakh/gemini-bridge.git\ncd gemini-bridge\npip install -e .\n\n# Add to Claude Code (development)\nclaude mcp add gemini-bridge-dev -s user -- python -m src\n```\n\n## \ud83d\udee0\ufe0f Available Tools\n\n### `consult_gemini`\nDirect CLI bridge for simple queries.\n\n**Parameters:**\n- `query` (string): The question or prompt to send to Gemini\n- `directory` (string): Working directory for the query (default: current directory)\n- `model` (string, optional): Model to use - \"flash\" or \"pro\" (default: \"flash\")\n\n**Example:**\n```python\nconsult_gemini(\n query=\"Find authentication patterns in this codebase\",\n directory=\"/path/to/project\",\n model=\"flash\"\n)\n```\n\n### `consult_gemini_with_files`\nCLI bridge with file attachments for detailed analysis.\n\n**Parameters:**\n- `query` (string): The question or prompt to send to Gemini\n- `directory` (string): Working directory for the query\n- `files` (list): List of file paths relative to the directory\n- `model` (string, optional): Model to use - \"flash\" or \"pro\" (default: \"flash\")\n\n**Example:**\n```python\nconsult_gemini_with_files(\n query=\"Analyze these auth files and suggest improvements\",\n directory=\"/path/to/project\",\n files=[\"src/auth.py\", \"src/models.py\"],\n model=\"pro\"\n)\n```\n\n## \ud83d\udccb Usage Examples\n\n### Basic Code Analysis\n```python\n# Simple research query\nconsult_gemini(\n query=\"What authentication patterns are used in this project?\",\n directory=\"/Users/dev/my-project\"\n)\n```\n\n### Detailed File Review\n```python\n# Analyze specific files\nconsult_gemini_with_files(\n query=\"Review these files and suggest security improvements\",\n directory=\"/Users/dev/my-project\",\n files=[\"src/auth.py\", \"src/middleware.py\"],\n model=\"pro\"\n)\n```\n\n### Multi-file Analysis\n```python\n# Compare multiple implementation files\nconsult_gemini_with_files(\n query=\"Compare these database implementations and recommend the best approach\",\n directory=\"/Users/dev/my-project\",\n files=[\"src/db/postgres.py\", \"src/db/sqlite.py\", \"src/db/redis.py\"]\n)\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### Core Design\n- **CLI-First**: Direct subprocess calls to `gemini` command\n- **Stateless**: Each tool call is independent with no session state\n- **Fixed Timeout**: 60-second maximum execution time\n- **Simple Error Handling**: Clear error messages with fail-fast approach\n\n### Project Structure\n```\ngemini-bridge/\n\u251c\u2500\u2500 src/\n\u2502 \u251c\u2500\u2500 __init__.py # Entry point\n\u2502 \u251c\u2500\u2500 __main__.py # Module execution entry point\n\u2502 \u2514\u2500\u2500 mcp_server.py # Main MCP server implementation\n\u251c\u2500\u2500 .github/ # GitHub templates and workflows\n\u251c\u2500\u2500 pyproject.toml # Python package configuration\n\u251c\u2500\u2500 README.md # This file\n\u251c\u2500\u2500 CONTRIBUTING.md # Contribution guidelines\n\u251c\u2500\u2500 CODE_OF_CONDUCT.md # Community standards\n\u251c\u2500\u2500 SECURITY.md # Security policies\n\u251c\u2500\u2500 CHANGELOG.md # Version history\n\u2514\u2500\u2500 LICENSE # MIT license\n```\n\n## \ud83d\udd27 Development\n\n### Local Testing\n```bash\n# Install in development mode\npip install -e .\n\n# Run directly\npython -m src\n\n# Test CLI availability\ngemini --version\n```\n\n### Integration with Claude Code\nThe server automatically integrates with Claude Code when properly configured through the MCP protocol.\n\n## \ud83d\udd0d Troubleshooting\n\n### CLI Not Available\n```bash\n# Install Gemini CLI\nnpm install -g @google/gemini-cli\n\n# Authenticate\ngemini auth login\n\n# Test\ngemini --version\n```\n\n### Connection Issues\n- Verify Gemini CLI is properly authenticated\n- Check network connectivity\n- Ensure Claude Code MCP configuration is correct\n- Check that the `gemini` command is in your PATH\n\n### Common Error Messages\n- **\"CLI not available\"**: Gemini CLI is not installed or not in PATH\n- **\"Authentication required\"**: Run `gemini auth login`\n- **\"Timeout after 60 seconds\"**: Query took too long, try breaking it into smaller parts\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions from the community! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on how to get started.\n\n### Quick Contributing Guide\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests if applicable\n5. Submit a pull request\n\n## \ud83d\udcc4 License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\udd04 Version History\n\nSee [CHANGELOG.md](CHANGELOG.md) for detailed version history.\n\n## \ud83c\udd98 Support\n\n- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/shelakh/gemini-bridge/issues)\n- **Discussions**: Join the community discussion\n- **Documentation**: Additional docs can be created in the `docs/` directory\n\n---\n\n**Focus**: A simple, reliable bridge between Claude Code and Gemini AI through the official CLI.\n",
"bugtrack_url": null,
"license": null,
"summary": "Lightweight MCP server bridging Claude Code to Google's Gemini AI via official CLI",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/eLyiN/gemini-bridge",
"Issues": "https://github.com/eLyiN/gemini-bridge/issues",
"Repository": "https://github.com/eLyiN/gemini-bridge"
},
"split_keywords": [
"mcp",
" gemini",
" ai",
" coding",
" assistant"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "3e2c81aede6dda4ffa6b534c1a9c2a8925da156749483326f370e4ef3f5e653d",
"md5": "e2a787f182eda2280dec9dd30b377a21",
"sha256": "c702e32c8ba9d00910e247513349f00283c2b3bb9aea5805725d583f6bd04e84"
},
"downloads": -1,
"filename": "gemini_bridge-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e2a787f182eda2280dec9dd30b377a21",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 7560,
"upload_time": "2025-08-25T16:08:21",
"upload_time_iso_8601": "2025-08-25T16:08:21.790640Z",
"url": "https://files.pythonhosted.org/packages/3e/2c/81aede6dda4ffa6b534c1a9c2a8925da156749483326f370e4ef3f5e653d/gemini_bridge-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "99dfa47ad5ad9d9072bf79b9b46eb1c51c4dcaeb001329c7409ad5438e154bf5",
"md5": "62f0a2eef516ae1483cec092d2d5a06d",
"sha256": "73d4b6a72c12b046cd0a0a4f58fc9b298a342fd47814fdc595dc336b00254c4f"
},
"downloads": -1,
"filename": "gemini_bridge-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "62f0a2eef516ae1483cec092d2d5a06d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 6841,
"upload_time": "2025-08-25T16:08:22",
"upload_time_iso_8601": "2025-08-25T16:08:22.524389Z",
"url": "https://files.pythonhosted.org/packages/99/df/a47ad5ad9d9072bf79b9b46eb1c51c4dcaeb001329c7409ad5438e154bf5/gemini_bridge-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-25 16:08:22",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "eLyiN",
"github_project": "gemini-bridge",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gemini-bridge"
}
