# Gemini CLI MCP Server

A Model Context Protocol (MCP) server and CLI wrapper for Google's Gemini CLI with OAuth authentication support. This allows you to use Gemini through Claude Desktop/Code without needing API keys - just login with your Google account.

## Features

- **OAuth Authentication**: Login with your Google account, no API keys required
- **MCP Server**: Full integration with Claude Desktop and Claude Code
- **CLI Tool**: Command-line interface for direct usage
- **Multi-Model Support**: Use different Gemini models (gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite)
- **File Analysis**: Analyze code and documents with context
- **Session Persistence**: Maintains authentication across sessions
- **Headless Mode**: Support for environments without browser access

## Installation

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

## Prerequisites

You need to have Google's Gemini CLI installed:

```bash
# Install globally
npm install -g @google/gemini-cli

# Or use npx
npx @google/gemini-cli
```

The Gemini CLI provides 60 requests/minute and 1,000 requests/day with a personal Google account.

## Quick Start

### 1. Initial Authentication

```bash
# The Gemini CLI handles authentication automatically on first use
# Just run any command and it will prompt for auth if needed
gemini-mcp query "Hello"

# Check authentication status
gemini-mcp auth-status
```

### 2. CLI Usage

```bash
# Send a query
gemini-mcp query "Explain quantum computing in simple terms"

# Query with specific model (defaults to 2.5-pro)
gemini-mcp query "Write a Python function for binary search" --model gemini-2.5-flash

# Analyze files
gemini-mcp analyze --files src/main.ts src/utils.ts --instruction "Find potential bugs"

# Query with context files
gemini-mcp query "Explain this code" --context main.py utils.py
```

### 3. MCP Server Configuration

Add to your Claude Desktop or Claude Code configuration:

```json
{
  "mcpServers": {
    "gemini": {
      "command": "npx",
      "args": ["-y", "@jacob/gemini-cli-mcp"],
      "env": {
        "GEMINI_MODEL": "gemini-2.5-pro",
        "GEMINI_TIMEOUT": "30000",
        "GEMINI_AUTO_LOGIN": "true",
        "GEMINI_THINKING_ENABLED": "true"
      }
    }
  }
}
```

## Available MCP Tools

### gemini_query
Query Gemini with a prompt and optional context files.

```typescript
{
  prompt: string;          // Your question or prompt
  model?: string;          // Optional: "gemini-2.5-pro" (default), "gemini-2.5-flash", or "gemini-2.5-flash-lite"
  context?: string[];      // Optional: Array of file paths for context
}
```

### gemini_analyze
Analyze files with specific instructions.

```typescript
{
  files: string[];         // Files to analyze
  instruction: string;     // Analysis instruction
  model?: string;          // Optional: Model to use
}
```

### gemini_auth_status
Check current authentication status.

### gemini_login
Initiate authentication flow.

```typescript
{
  headless?: boolean;      // Show URL instead of opening browser
  account?: string;        // Specific Google account to use
}
```

### gemini_list_models
List available Gemini models.

## CLI Commands

### Authentication Commands

```bash
# Login
gemini-mcp login [options]
  --headless              # Display URL instead of opening browser
  --account <email>       # Specify Google account

# Logout
gemini-mcp logout

# Check auth status
gemini-mcp auth-status
```

### Query Commands

```bash
# Send query
gemini-mcp query <prompt> [options]
  -m, --model <model>     # Model to use
  -c, --context <files>   # Context files
  -t, --timeout <ms>      # Timeout in milliseconds

# Analyze files
gemini-mcp analyze [options]
  -f, --files <files>     # Files to analyze (required)
  -i, --instruction <text> # Analysis instruction (required)
  -m, --model <model>     # Model to use
```

### Configuration

```bash
# Set configuration
gemini-mcp config --set key=value

# Get configuration
gemini-mcp config --get key

# List all configuration
gemini-mcp config --list
```

Configuration options:
- `model`: Default model (gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite)
- `timeout`: Request timeout in milliseconds
- `headlessDefault`: Default to headless authentication
- `autoLogin`: Automatically login if not authenticated
- `thinkingEnabled`: Enable thinking mode by default (shows model's reasoning)
- `thinkingBudget`: Default token budget for thinking process

## Environment Variables

- `GEMINI_MODEL`: Default model to use (gemini-2.5-pro, gemini-2.5-flash, gemini-2.5-flash-lite)
- `GEMINI_TIMEOUT`: Request timeout (ms)
- `GEMINI_AUTH_CACHE`: Authentication cache directory
- `GEMINI_HEADLESS`: Default to headless mode
- `GEMINI_AUTO_LOGIN`: Auto-login on first use
- `GEMINI_THINKING_ENABLED`: Enable thinking mode by default
- `GEMINI_THINKING_BUDGET`: Default thinking token budget

## Examples

### Example 1: Code Review

```bash
# Analyze a TypeScript project for issues
gemini-mcp analyze \
  --files "src/**/*.ts" \
  --instruction "Review this code for potential bugs, security issues, and suggest improvements"
```

### Example 2: Documentation Generation

```bash
# Generate documentation for a module with thinking mode
gemini-mcp query "Generate comprehensive JSDoc documentation for this module" \
  --context src/auth-manager.ts \
  --model gemini-2.5-flash \
  --thinking-enabled
```

### Example 3: Using in Scripts

```bash
#!/bin/bash

# Check if authenticated
if ! gemini-mcp auth-status > /dev/null 2>&1; then
  echo "Please login first: gemini-mcp login"
  exit 1
fi

# Run analysis
gemini-mcp analyze --files "$@" --instruction "Find security vulnerabilities"
```

## Troubleshooting

### Authentication Issues

1. **Browser doesn't open**: Use `--headless` flag and manually visit the URL
2. **Session expired**: Run `gemini-mcp login` again
3. **Wrong account**: Use `--account email@gmail.com` to specify account

### Connection Issues

1. Ensure Gemini CLI is installed and in PATH
2. Check internet connectivity
3. Verify Google account has access to Gemini

### MCP Server Issues

1. Restart Claude Desktop/Code after configuration changes
2. Check logs for error messages
3. Verify the MCP server is running: `npx @jacob/gemini-cli-mcp`

## Security

- Authentication tokens are stored locally in `~/.gemini-cli-mcp/auth/`
- Tokens are only accessible by your user account
- Use `gemini-mcp logout` to clear stored credentials
- Never share your authentication cache directory

## Development

```bash
# Clone the repository
git clone https://github.com/yourusername/gemini-cli-mcp.git
cd gemini-cli-mcp

# Install dependencies
npm install

# Build
npm run build

# Run locally
npm start

# Development mode
npm run dev
```

## License

MIT

## Contributing

Contributions are welcome! Please read our contributing guidelines and submit pull requests to our repository.

## Support

For issues and feature requests, please use the GitHub issue tracker.