Content
# Gemini MCP Server
A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server providing **23 tools** for Google's Gemini API -- chat, multimodal analysis, deep research, file management, YouTube analysis, and more.
Built with [`@google/genai`](https://www.npmjs.com/package/@google/genai) SDK (v1.0.0+).
## Features
- Chat with Gemini models (single-turn, multi-turn, with tool modes)
- Analyze images, audio, video, PDFs, YouTube videos, and URLs
- Files API with auto-switching: inline for small files (<20MB), upload for large (up to 2GB)
- Deep research agent with background polling and push notifications (Termux)
- Structured JSON output, embeddings, code execution, translation, summarization
- Google Search grounding and URL context
- Thinking mode enabled by default (budget: 65535 tokens)
- High media resolution by default
## Prerequisites
- **Node.js 18+**
- A [Gemini API key](https://aistudio.google.com/apikey)
## Quick Install
```bash
git clone https://github.com/salviz/gemini-mcp-server.git
cd gemini-mcp-server
npm install
```
### Register with Claude Code
CLI:
```bash
claude mcp add gemini -- node /path/to/gemini-mcp-server/index.js
```
Or add to your MCP config (`~/.claude/claude_desktop_config.json` or `.mcp.json`):
```json
{
"mcpServers": {
"gemini": {
"type": "stdio",
"command": "node",
"args": ["/path/to/gemini-mcp-server/index.js"],
"env": {
"GEMINI_API_KEY": "your-api-key"
}
}
}
}
```
## Environment Variables
| Variable | Required | Description |
|----------|----------|-------------|
| `GEMINI_API_KEY` | Yes | Your Google Gemini API key |
## Tools (23)
### Chat & Generation (6)
| Tool | Description |
|------|-------------|
| `gemini_chat` | Send a prompt with optional search grounding and URL context |
| `gemini_chat_multi` | Multi-turn conversation with message history |
| `gemini_chat_with_tools` | Chat with mode switching: `search`, `code`, or `all` |
| `gemini_search_grounded` | Search-grounded generation with source citations |
| `gemini_structured_output` | Generate JSON output matching a provided schema |
| `gemini_url_context` | Analyze one or more URLs using Gemini's URL context tool |
### Multimodal Analysis (6)
| Tool | Description |
|------|-------------|
| `gemini_analyze_image` | Analyze an image file with Gemini Vision (JPG, PNG, GIF, WebP, BMP, SVG) |
| `gemini_analyze_audio` | Transcribe, summarize, or describe audio (MP3, WAV, OGG, FLAC, AAC, M4A, Opus) |
| `gemini_analyze_video` | Analyze a video file; auto-uploads large files via Files API (MP4, AVI, MOV, MKV, WebM) |
| `gemini_analyze_pdf` | Analyze a PDF document (up to 2GB via Files API) |
| `gemini_analyze_youtube` | Analyze a public YouTube video by URL (no download needed) |
| `gemini_analyze_url` | Analyze content from an HTTP/HTTPS URL or GCS URI (`gs://`) |
### Deep Research (2)
| Tool | Description |
|------|-------------|
| `gemini_deep_research` | Start a deep research task; sends push notification on completion |
| `gemini_check_research` | Check status of a running deep research task by interaction ID |
### Files API (3)
| Tool | Description |
|------|-------------|
| `gemini_upload_file` | Upload a file to Gemini (up to 2GB, retained 48 hours) |
| `gemini_list_files` | List all uploaded files with metadata |
| `gemini_delete_file` | Delete an uploaded file by name |
### Utilities (6)
| Tool | Description |
|------|-------------|
| `gemini_list_models` | List available Gemini models with capabilities and token limits |
| `gemini_count_tokens` | Count tokens in text using a model's tokenizer |
| `gemini_embed` | Generate text embeddings (default: `gemini-embedding-001`, 3072 dimensions) |
| `gemini_code_execute` | Execute Python code via Gemini's built-in sandbox |
| `gemini_summarize` | Summarize text with configurable style (brief, detailed, bullet-points) |
| `gemini_translate` | Translate text to any language with optional model override |
## Model Selection
Default model: **`gemini-3.1-pro-preview`**. Every tool accepts an optional `model` parameter.
| Model | Best For |
|-------|----------|
| `gemini-3.1-pro-preview` | Default. Best quality for most tasks |
| `gemini-2.5-flash` | Faster responses, lower cost |
| `gemini-embedding-001` | Text embeddings (used by `gemini_embed`) |
| `deep-research-pro-preview-12-2025` | Deep research agent (used internally) |
## Files API & Large File Handling
The server automatically handles file size:
- **<= 20MB**: Sent inline as base64 (fast, no upload step)
- **> 20MB up to 2GB**: Uploaded via Gemini Files API, then referenced by URI
- **YouTube URLs**: Passed directly via `fileData.fileUri` (no download)
- **HTTP/HTTPS URLs**: Passed via `createPartFromUri` (up to 100MB)
- **GCS URIs** (`gs://`): Passed via `fileData.fileUri`
Uploaded files are retained for 48 hours. Use `gemini_list_files` and `gemini_delete_file` to manage them.
## Deep Research
The `gemini_deep_research` tool uses Gemini's Interactions API with the `deep-research-pro-preview-12-2025` agent:
1. Starts research in background mode
2. Polls for 50 seconds in case it finishes quickly
3. If still running, starts background polling (every 30s, up to 30 minutes)
4. Sends a **push notification** via `termux-notification` when complete
5. Saves full results to `~/.cache/deep_research_*.txt`
Use `gemini_check_research` to manually poll at any time.
## Project Structure
```
gemini-mcp-server/
index.js # Server entry point
tools/
shared.js # Shared config, AI client, extractText helper
chat.js # 17 tools: chat, analysis, research, files, YouTube
utility.js # 6 tools: models, tokens, embed, code, summarize, translate
package.json
```
## Security
- **API key from environment only** -- never hardcoded in source
- **File paths validated** -- absolute paths required, existence checked before reading
- **Stdio transport** -- no network server exposed
- **No data logged or stored** -- prompts and responses are not persisted
## Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| `@modelcontextprotocol/sdk` | ^1.0.0 | MCP server framework |
| `@google/genai` | ^1.0.0 | Google Gemini AI SDK |
| `zod` | ^3.24.0 | Input schema validation |
## License
MIT
