@yusukedev/gemini-cli-mcp/README.md

A secure Model Context Protocol server for Gemini CLI with automatic fallback, extended timeout (180s), and model transparency features

# Gemini CLI MCP Server

A secure Model Context Protocol (MCP) server that provides access to Google's Gemini CLI functionality through standardized MCP tools.

## ✨ Features

- 💬 **Chat Integration**: Direct conversation with Gemini models for development consultation and code assistance
- 🔄 **Automatic Fallback**: Seamlessly switches from Gemini 2.5 Pro to Flash when quota limits are reached
- 🛡️ **Secure Implementation**: Uses temporary files to prevent shell injection vulnerabilities
- ⚡ **Extended Timeout**: 180-second timeout for processing complex queries
- 🚀 **Easy Integration**: Simple setup with Claude Desktop and other MCP-compatible clients
- 📊 **Model Transparency**: Response includes information about which model was used (Pro or Flash)

## 🔧 Prerequisites

1. **Node.js 18+** is required
2. **Gemini CLI** must be installed and authenticated:
   ```bash
   npm install -g @google/generative-ai-cli
   gemini auth
   ```

### Installation

Install globally via npm:

```bash
npm install -g @yusukedev/gemini-cli-mcp
```

Or use directly with npx:

```bash
npx @yusukedev/gemini-cli-mcp
```

### Configuration

Add to your Claude Desktop `claude_desktop_config.json` file (or similar MCP client configuration):

```json
{
  "mcpServers": {
    "gemini-cli": {
      "command": "npx",
      "args": ["@yusukedev/gemini-cli-mcp"]
    }
  }
}
```

Or if installed globally:

```json
{
  "mcpServers": {
    "gemini-cli": {
      "command": "gemini-cli-mcp"
    }
  }
}
```

## 🛠️ Available Tools

### `gemini_chat_pro`

Chat with Gemini 2.5 Pro for development consultation and code assistance.  
If this tool fails（quota exceeded, etc.）, use `gemini_chat_flash` as a fallback.

**Parameters:**
- `message` (required): The message or question to send to Gemini
- `context` (optional): Additional context or code to include in the conversation

**Example:**
```javascript
{
  "name": "gemini_chat_pro",
  "arguments": {
    "message": "Review this TypeScript code for potential improvements",
    "context": "function validateEmail(email: string): boolean { return /\\S+@\\S+\\.\\S+/.test(email); }"
  }
}
```

### `gemini_chat_flash`

Chat with Gemini 2.5 Flash for development consultation and code assistance.  
Use this if `gemini_chat_pro` fails.

**Parameters:**
- `message` (required): The message or question to send to Gemini
- `context` (optional): Additional context or code to include in the conversation

**Example:**
```javascript
{
  "name": "gemini_chat_flash",
  "arguments": {
    "message": "Review this TypeScript code for potential improvements",
    "context": "function validateEmail(email: string): boolean { return /\\S+@\\S+\\.\\S+/.test(email); }"
  }
}
```


## 🔄 Automatic Fallback

The server automatically handles quota limits by:

1. **Primary**: Attempts to use `gemini-2.5-pro` (high quality)
2. **Fallback**: Switches to `gemini-2.5-flash` if Pro quota is exceeded
3. **Transparency**: Response includes model information and fallback status

## 📋 System Requirements

- **Node.js**: 18.0.0 or higher
- **OS**: Windows, macOS, Linux (with WSL)
- **Gemini CLI**: [Google AI Studio](https://ai.google.dev/)

## 🐛 Debugging

Since MCP servers operate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:

```bash
npm run inspector
```

## 📄 License

MIT License

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 🔗 Links

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Google AI Studio](https://ai.google.dev/)
- [Gemini CLI Documentation](https://www.npmjs.com/package/@google/generative-ai-cli)