Content
# 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.
