mcp-gemini-cli/README.md

MCP server wrapper for Google's Gemini CLI

# MCP Gemini CLI

A simple MCP server wrapper for Google's Gemini CLI that enables AI assistants to use Gemini's capabilities through the Model Context Protocol.

## What it does

This server exposes three tools that interact with Gemini CLI:

- `googleSearch`: Asks Gemini to perform a Google search using your query
- `chat`: Sends prompts directly to Gemini for general conversations
- `analyzeFile`: Analyzes files (images, PDFs, text) using Gemini's multimodal capabilities

## Prerequisites

- [Gemini CLI](https://github.com/google-gemini/gemini-cli) installed and configured (optional with --allow-npx flag)

## 🚀 Quick Start with Claude Code

### 1. Add the MCP server

```bash
claude mcp add -s project gemini-cli -- npx mcp-gemini-cli --allow-npx
```

Or configure your MCP client with the settings shown in the Installation Options section below.

### 2. Try it out

Example prompts:

- **Search**: "Search for the latest TypeScript 5.0 features using Google"
- **Chat**: "Ask Gemini to explain the difference between async/await and promises in JavaScript"
- **File Analysis**: "Ask Gemini to analyze the image at /path/to/screenshot.png"

## 🔧 Installation Options

### Using npx with --allow-npx flag

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

### Local Development

1. Clone and install:

```bash
git clone https://github.com/choplin/mcp-gemini-cli
cd mcp-gemini-cli
bun install
```

1. Add to Claude Desktop config:

```json
{
  "mcpServers": {
    "mcp-gemini-cli": {
      "command": "bun",
      "args": ["run", "/path/to/mcp-gemini-cli/index.ts"]
    }
  }
}
```

## 🛠️ Available Tools

### 1. googleSearch

Performs a Google search using Gemini CLI.

**Parameters:**

- `query` (required): The search query
- `limit` (optional): Maximum number of results
- `sandbox` (optional): Run in sandbox mode
- `yolo` (optional): Skip confirmations
- `model` (optional): Gemini model to use (default: "gemini-2.5-pro")

### 2. chat

Have a conversation with Gemini.

**Parameters:**

- `prompt` (required): The conversation prompt
- `sandbox` (optional): Run in sandbox mode
- `yolo` (optional): Skip confirmations
- `model` (optional): Gemini model to use (default: "gemini-2.5-pro")

### 3. analyzeFile

Analyze files using Gemini's multimodal capabilities.

**Supported file types:**

- **Images**: PNG, JPG, JPEG, GIF, WEBP, SVG, BMP
- **Text**: TXT, MD, TEXT
- **Documents**: PDF

**Parameters:**

- `filePath` (required): The absolute path to the file to analyze
- `prompt` (optional): Additional instructions for analyzing the file
- `sandbox` (optional): Run in sandbox mode
- `yolo` (optional): Skip confirmations
- `model` (optional): Gemini model to use (default: "gemini-2.5-pro")

## 💡 Example Prompts

Try these prompts to see mcp-gemini-cli in action:

- **Search**: "Search for the latest TypeScript 5.0 features using Google"
- **Chat**: "Ask Gemini to explain the difference between async/await and promises in JavaScript"
- **File Analysis**: "Ask Gemini to describe what's in this image: /Users/me/Desktop/screenshot.png"

## 🛠️ Example Usage

### googleSearch

```typescript
// Simple search
googleSearch({ query: "latest AI news" });

// Search with limit
googleSearch({
  query: "TypeScript best practices",
  limit: 5,
});
```

### chat

```typescript
// Simple chat
chat({ prompt: "Explain quantum computing in simple terms" });

// Using a different model
chat({
  prompt: "Write a haiku about programming",
  model: "gemini-2.5-flash",
});
```

### analyzeFile

```typescript
// Analyze an image
analyzeFile({ 
  filePath: "/path/to/image.png",
  prompt: "What objects are in this image?"
});

// Analyze a PDF
analyzeFile({
  filePath: "/path/to/document.pdf",
  prompt: "Summarize the key points in this document"
});

// General analysis without specific instructions
analyzeFile({ filePath: "/path/to/file.jpg" });
```

## 📝 Development

> **Note**: Development requires [Bun](https://bun.sh) runtime.

### Run in Development Mode

```bash
bun run dev
```

### Run Tests

```bash
bun test
```

### Build for Production

```bash
# Development build
bun run build

# Production build (minified)
bun run build:prod
```

### Linting & Formatting

```bash
# Lint code
bun run lint

# Format code
bun run format
```

## 🤝 Contributing

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

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 📋 Changelog

### [0.3.1] - 2025-07-03

#### Fixed

- Fixed Windows compatibility issue with `which` command

### [0.3.0] - 2025-07-02

#### Breaking Changes

- Tool names: `geminiChat` → `chat`, `geminiAnalyzeFile` → `analyzeFile`
- Package name: `@choplin/mcp-gemini-cli` → `mcp-gemini-cli`

#### New Features

- `analyzeFile` tool for images (PNG/JPG/GIF/etc), PDFs, and text files

### [0.2.0] - Previous

- Initial release with `googleSearch` and `geminiChat` tools

## 🔗 Related Links

- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/)
- [Gemini CLI](https://github.com/google-gemini/gemini-cli)
- [Bun Runtime](https://bun.sh)