README.md•13.9 kB
# 🚀 Gemini MCP Tool - Windows Fixed Version
[](https://badge.fury.io/js/gemini-mcp-tool-windows-fixed)
[](https://opensource.org/licenses/MIT)
> **Latest Version v1.0.21** - Fixed cross-terminal compatibility issues and fetch-chunk format errors
A **Windows-compatible** Model Context Protocol (MCP) server that enables AI assistants to interact with Google's Gemini CLI. This is a fixed version specifically designed to work seamlessly on Windows environments with PowerShell support.
> **Note**: This is an enhanced version of the [original gemini-mcp-tool](https://github.com/jamubc/gemini-mcp-tool) with Windows-specific fixes and improvements.
## 🆕 Latest Updates (v1.0.21)
- 🔧 **Fixed Cross-Terminal Compatibility** - Resolved Node.js path not found issues in different terminal environments
- 📦 **Fixed fetch-chunk Format Error** - Fixed MCP protocol format mismatch in chunked responses
- 🛡️ **Enhanced PATH Environment Variable Handling** - Automatically adds common Node.js installation paths
- ✅ **Full Compatibility with All Terminals** - Supports PowerShell, CMD, VS Code Terminal, Trae AI, CherryStudio, etc.
- 🚀 **Improved Error Handling** - Better error messages and debug output
### v1.0.3 Updates
- 🆕 **PowerShell Path Parameter Support** - Added optional `powershellPath` parameter allowing users to customize PowerShell executable path
- ✅ **Fixed PowerShell Execution Error** - Resolved `spawn powershell.exe ENOENT` issue
- ✅ **Improved Windows Compatibility** - Automatic detection of available PowerShell versions
- ✅ **Fixed Undefined Variable Error** - Fixed `args` variable issue in `executeCommandWithPipedInput` function
- ✅ **Enhanced Error Handling** - Better error messages and debug output
- ✅ **Backward Compatibility** - Existing configurations require no modification, automatically uses default detection logic
## ✨ Features
- **🪟 Windows Compatible**: Full PowerShell support with Windows-specific path handling
- **📊 Large Context Window**: Leverage Gemini's massive token window for analyzing entire codebases
- **📁 File Analysis**: Analyze files using `@filename` syntax
- **🔒 Sandbox Mode**: Safe code execution environment
- **🔗 MCP Integration**: Seamless integration with MCP-compatible AI assistants (Trae AI, Claude Desktop)
- **⚡ NPX Ready**: Easy installation and usage with NPX
- **🔧 Environment Variable Support**: Flexible API key configuration
This Windows-fixed version resolves:
- PowerShell parameter passing issues
- Character encoding problems with Chinese/Unicode text
- Command line argument escaping on Windows
- Environment variable handling
## 📋 Prerequisites
Before using this tool, ensure you have:
1. **[Node.js](https://nodejs.org/)** (v16.0.0 or higher)
```powershell
node --version # Should be v16+
```
2. **[Google Gemini CLI](https://github.com/google-gemini/gemini-cli)** installed and **configured**
```powershell
npm install -g @google/generative-ai-cli
# Verify installation
gemini --version
```
3. **API Key**: Get your API key from [Google AI Studio](https://makersuite.google.com/app/apikey)
## 📦 Installation
### Quick Start with NPX (Recommended)
```powershell
# Use latest version (recommended)
npx gemini-mcp-tool-windows-fixed@1.0.21
# Or use latest version tag
npx -y gemini-mcp-tool-windows-fixed@latest
```
### Global Installation
```powershell
# Install latest version
npm install -g gemini-mcp-tool-windows-fixed@1.0.21
# Run the tool
gemini-mcp-tool-windows-fixed
```
### Updating Existing Installation
If you previously installed an older version:
```powershell
# Uninstall old version and install latest
npm uninstall -g gemini-mcp-tool-windows-fixed
npm cache clean --force
npm install -g gemini-mcp-tool-windows-fixed@1.0.21
```
## ⚙️ MCP Client Configuration
### Claude Code (One-Line Setup)
```bash
# One-command setup for Claude Code
claude mcp add gemini-cli -- npx -y gemini-mcp-tool-windows-fixed@1.0.21
```
**Verify Installation:**
Type `/mcp` inside Claude Code to verify the `gemini-cli` MCP is active. <mcreference link="https://github.com/jamubc/gemini-mcp-tool" index="1">1</mcreference>
### Alternative: Import from Claude Desktop
If you already have it configured in Claude Desktop:
1. Add to your Claude Desktop config (see below)
2. Import to Claude Code:
```bash
claude mcp add-from-claude-desktop
```
### Trae AI (Recommended)
1. Open: `%APPDATA%\Trae\User\mcp.json`
2. Add this configuration:
```json
{
"mcpServers": {
"gemini-cli": {
"name": "gemini-cli",
"description": "Windows-compatible Gemini MCP Tool",
"baseUrl": "",
"command": "npx",
"args": [
"-y",
"gemini-mcp-tool-windows-fixed@1.0.21"
],
"env": {
"GEMINI_API_KEY": "YOUR_ACTUAL_API_KEY_HERE"
},
"isActive": true,
"providerUrl": "https://github.com/orzcls/gemini-mcp-tool-windows-fixed"
}
}
}
```
### Claude Desktop
1. Open: `%APPDATA%\Claude\claude_desktop_config.json`
2. Add this configuration:
```json
{
"mcpServers": {
"gemini-cli": {
"command": "npx",
"args": ["-y", "gemini-mcp-tool-windows-fixed@1.0.21"],
"env": {
"GEMINI_API_KEY": "YOUR_ACTUAL_API_KEY_HERE"
}
}
}
}
```
## 🔑 API Key Configuration
### Option 1: MCP Configuration (Recommended)
Replace `YOUR_ACTUAL_API_KEY_HERE` in the configuration above with your actual API key.
### Option 2: Environment Variable
```powershell
# Temporary (current session)
$env:GEMINI_API_KEY = "your-actual-api-key"
# Permanent (user level)
[Environment]::SetEnvironmentVariable("GEMINI_API_KEY", "your-actual-api-key", "User")
# Verify
echo $env:GEMINI_API_KEY
```
### Configuration File Locations
**Claude Desktop:**
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Linux**: `~/.config/claude/claude_desktop_config.json`
**Trae AI:**
- **Windows**: `%APPDATA%\Trae\User\mcp.json`
## 🛠️ Available Tools
This MCP server provides the following tools for AI assistants:
### 1. `ask-gemini`
Interact with Google Gemini for analysis and questions.
**Parameters:**
- `prompt` (required): The analysis request. Use `@` syntax for file references
- `model` (optional): Gemini model to use (default: `gemini-2.5-pro`)
- `sandbox` (optional): Enable sandbox mode for safe code execution
- `changeMode` (optional): Enable structured change mode
- `chunkIndex` (optional): Chunk index for continuation
- `chunkCacheKey` (optional): Cache key for continuation
### 2. `brainstorm`
Generate creative ideas using various brainstorming frameworks.
**Parameters:**
- `prompt` (required): Brainstorming challenge or question
- `model` (optional): Gemini model to use
- `methodology` (optional): Framework (`divergent`, `convergent`, `scamper`, `design-thinking`, `lateral`, `auto`)
- `domain` (optional): Domain context (`software`, `business`, `creative`, etc.)
- `constraints` (optional): Known limitations or requirements
- `existingContext` (optional): Background information
- `ideaCount` (optional): Number of ideas to generate (default: 12)
- `includeAnalysis` (optional): Include feasibility analysis (default: true)
### 3. `fetch-chunk`
Retrieve cached chunks from changeMode responses.
**Parameters:**
- `cacheKey` (required): Cache key from initial response
- `chunkIndex` (required): Chunk index to retrieve (1-based)
### 4. `timeout-test`
Test timeout prevention mechanisms.
**Parameters:**
- `duration` (required): Duration in milliseconds (minimum: 10ms)
### 5. `ping`
Test connection to the server.
**Parameters:**
- `prompt` (optional): Message to echo back
### 6. `Help`
Display help information about available tools.
## 🎯 Usage Examples
Once configured, you can use the following tools through your MCP client:
### Natural Language Examples <mcreference link="https://github.com/jamubc/gemini-mcp-tool" index="2">2</mcreference>
**With File References (using @ syntax):**
- "ask gemini to analyze @src/main.js and explain what it does"
- "use gemini to summarize @. the current directory"
- "analyze @package.json and tell me about dependencies"
**General Questions (without files):**
- "ask gemini to search for the latest tech news"
- "use gemini to explain div centering"
- "ask gemini about best practices for React development related to @file_im_confused_about"
- "use gemini to explain index.html"
- "understand the massive project using gemini"
- "ask gemini to search for latest news"
**Using Gemini CLI's Sandbox Mode (-s):** <mcreference link="https://github.com/jamubc/gemini-mcp-tool" index="2">2</mcreference>
The sandbox mode allows you to safely test code changes, run scripts, or execute potentially risky operations in an isolated environment.
- "use gemini sandbox to create and run a Python script that processes data"
- "ask gemini to safely test @script.py and explain what it does"
- "use gemini sandbox to install numpy and create a data visualization"
- "test this code safely: Create a script that makes HTTP requests to an API"
### Slash Commands (for Claude Code Users) <mcreference link="https://github.com/jamubc/gemini-mcp-tool" index="2">2</mcreference>
You can use these commands directly in Claude Code's interface (compatibility with other clients has not been tested):
- **/analyze**: Analyzes files or directories using Gemini, or asks general questions
- `prompt` (required): The analysis prompt. Use @ syntax to include files (e.g., `/analyze prompt:@src/ summarize this directory`) or ask general questions (e.g., `/analyze prompt:Please use a web search to find the latest news stories`)
- **/sandbox**: Safely tests code or scripts in Gemini's sandbox environment
- `prompt` (required): Code testing request (e.g., `/sandbox prompt:Create and run a Python script that processes CSV data` or `/sandbox prompt:@script.py Test this script safely`)
- **/help**: Displays the Gemini CLI help information
- **/ping**: Tests the connection to the server
- `message` (optional): A message to echo back
### Available Tools
- **ask-gemini**: Send prompts to Gemini
```
"Explain how MCP works"
```
- **analyze-file**: Analyze specific files using `@filename` syntax
```
"Analyze @package.json and suggest improvements"
```
- **sandbox-mode**: Execute code in a safe environment
```
"Run this Python code in sandbox mode: print('Hello World')"
```
## 🔧 Windows-Specific Fixes
This version includes the following Windows-specific improvements:
1. **PowerShell Parameter Handling**: Fixed argument passing to avoid parameter splitting
2. **Character Encoding**: Proper UTF-8 handling for Chinese and Unicode characters
3. **Quote Escaping**: Correct escaping of quotes in command arguments
4. **Environment Variables**: Improved `.env` file loading and environment variable handling
5. **Path Resolution**: Windows-compatible path handling
## 🧪 Testing Installation
### 1. Test Gemini CLI
```powershell
gemini -p "Hello, how are you?"
```
### 2. Test MCP Tool
```powershell
npx -y gemini-mcp-tool-windows-fixed
# Should show: [GMCPT] Gemini CLI MCP Server (Fixed) started
```
### 3. Test MCP Integration
1. Restart your MCP client (Trae AI, Claude Desktop)
2. Try asking: "Use gemini to explain what MCP is"
3. Check for successful responses
## 🐛 Troubleshooting
### Common Issues
#### "Command not found: gemini"
```powershell
npm install -g @google/generative-ai-cli
```
#### "API key not found"
```powershell
# Check if API key is set
echo $env:GEMINI_API_KEY
# Set if empty
$env:GEMINI_API_KEY = "your-api-key"
```
#### "Permission denied"
```powershell
# Check execution policy
Get-ExecutionPolicy
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
For detailed troubleshooting, see [INSTALL-GUIDE.md](./INSTALL-GUIDE.md).
## 🔧 Windows-Specific Fixes
This version includes several Windows-specific improvements:
- **PowerShell Integration**: Native PowerShell command execution
- **Path Handling**: Proper Windows path resolution
- **Environment Variables**: Enhanced environment variable support
- **Error Handling**: Better error messages for Windows environments
- **Dependency Management**: Simplified dependency structure
## 🤝 Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Test on Windows environments
4. Submit a pull request
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Original project: [jamubc/gemini-mcp-tool](https://github.com/jamubc/gemini-mcp-tool)
- Google Gemini CLI team
- Model Context Protocol (MCP) community
## 📞 Support
If you encounter any issues or have questions:
1. Check the [Issues](https://github.com/your-username/gemini-mcp-tool-windows-fixed/issues) page
2. Create a new issue with detailed information about your problem
3. Include your Windows version, Node.js version, and error messages
---
**Made with ❤️ for Windows developers**
**Note**: This is a Windows-optimized fork of the original gemini-mcp-tool. For other platforms, consider using the [original version](https://github.com/jamubc/gemini-mcp-tool).