Gemini CLI MCP server
Enables AI assistants to perform Google searches, chat with Gemini, and analyze multimodal files like images and PDFs.
Also known as choplin/mcp-gemini-cli, @choplin/mcp-gemini-cli
- Stars
- 101
- Tools
- 7
- Downloads, 30 days
- 4,025
- Latest version
- —
- Last commit
- Jul 3, 2025
- License
- —
What is Gemini CLI MCP?
Gemini CLI enables AI assistants to perform Google searches, chat with Gemini, and analyze multimodal files like images and PDFs. It exposes 7 tools, such as query, limit, sandbox.
Summary generated from the project's README
About Gemini CLI MCP server
Connecting AI assistants to Google's Gemini capabilities is what this server enables through the Model Context Protocol. It acts as a wrapper for the Gemini CLI, allowing clients like Claude Code or Claude Desktop to perform web searches, engage in direct conversations, and process multimodal files. Users can run it via npx with the --allow-npx flag or through local development using the Bun runtime.
The server provides three specific tools: googleSearch for web queries, chat for general prompts, and analyzeFile for examining documents and images. When using these tools, you can specify different models, such as gemini-2.5-pro or gemini-2.5-flash, and control search limits or sandbox modes. It supports a wide range of file types including PDFs, text files, and various image formats like PNG, JPG, and SVG.
What you can do with it
- 1Perform web searchesAsk your AI assistant to find the latest technical documentation or news using Google.
- 2Chat with Gemini modelsDirectly prompt Gemini to explain complex programming concepts or write creative content.
- 3Analyze multimodal filesProvide an absolute path to an image or PDF to have the AI describe or summarize its contents.
Written from the project's README. Every use case is checked against a quote from it.
How to install Gemini CLI MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall Gemini CLI MCP in Claude Code
$ claude mcp add mcp-gemini-cli -- npx -y @choplin/mcp-gemini-cliInstall Gemini CLI MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"mcp-gemini-cli": {
"command": "npx",
"args": [
"-y",
"@choplin/mcp-gemini-cli"
]
}
}
}Install Gemini CLI MCP in VS Code
.vscode/mcp.json
{
"servers": {
"mcp-gemini-cli": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@choplin/mcp-gemini-cli"
]
}
}
}Install Gemini CLI MCP in VS Code CLI
$ code --add-mcp '{"name":"mcp-gemini-cli","type":"stdio","command":"npx","args":["-y","@choplin/mcp-gemini-cli"]}'Install Gemini CLI MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"mcp-gemini-cli": {
"command": "npx",
"args": [
"-y",
"@choplin/mcp-gemini-cli"
]
}
}
}Install Gemini CLI MCP in Codex
$ codex mcp add mcp-gemini-cli -- npx -y @choplin/mcp-gemini-cliInstall Gemini CLI MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.mcp-gemini-cli] command = "npx" args = ["-y", "@choplin/mcp-gemini-cli"]
Install Gemini CLI MCP in Gemini CLI
$ gemini mcp add -s user mcp-gemini-cli npx -- -y @choplin/mcp-gemini-cliInstall Gemini CLI MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"mcp-gemini-cli": {
"command": "npx",
"args": [
"-y",
"@choplin/mcp-gemini-cli"
]
}
}
}Gemini CLI MCP tools 7
Detected from the READMEquerylimitsandboxyolomodelpromptfilePath
Automated checks
Ran Nov 14, 2026Full report →Not verified yet. A server needs a score of 80, no serious finding, and enough data for us to check. How checks work · What to fix for more points
- Source repository linked and reachablechoplin/mcp-gemini-cli is public and reachablegithub.com/choplin/mcp-gemini-cli ↗Pass
- Package names this repository as its source@choplin/mcp-gemini-cli, mcp-gemini-cli name choplin/mcp-gemini-cli as sourcenpmjs.com/package/@choplin/mcp-gemini-cli ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)No licenseFinding
- Commit or release in the last yearLast commit or release 2025-07-03github.com/choplin/mcp-gemini-cli ↗Finding
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @choplin/mcp-gemini-cli, mcp-gemini-cliPass
- No critical advisory in the package or its dependenciesNot checked
- No hidden instructions to the model7 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubMCP 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 querychat: Sends prompts directly to Gemini for general conversationsanalyzeFile: Analyzes files (images, PDFs, text) using Gemini's multimodal capabilities
Prerequisites
- Gemini CLI installed and configured (optional with --allow-npx flag)
🚀 Quick Start with Claude Code
1. Add the MCP server
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
{
"mcpServers": {
"mcp-gemini-cli": {
"command": "npx",
"args": ["mcp-gemini-cli", "--allow-npx"]
}
}
}
Local Development
- Clone and install:
git clone https://github.com/choplin/mcp-gemini-cli
cd mcp-gemini-cli
bun install
- Add to Claude Desktop config:
{
"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 querylimit(optional): Maximum number of resultssandbox(optional): Run in sandbox modeyolo(optional): Skip confirmationsmodel(optional): Gemini model to use (default: "gemini-2.5-pro")
2. chat
Have a conversation with Gemini.
Parameters:
prompt(required): The conversation promptsandbox(optional): Run in sandbox modeyolo(optional): Skip confirmationsmodel(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 analyzeprompt(optional): Additional instructions for analyzing the filesandbox(optional): Run in sandbox modeyolo(optional): Skip confirmationsmodel(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
// Simple search
googleSearch({ query: "latest AI news" });
// Search with limit
googleSearch({
query: "TypeScript best practices",
limit: 5,
});
chat
// 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
// 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 runtime.
Run in Development Mode
bun run dev
Run Tests
bun test
Build for Production
# Development build
bun run build
# Production build (minified)
bun run build:prod
Linting & Formatting
# 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
whichcommand
[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
analyzeFiletool for images (PNG/JPG/GIF/etc), PDFs, and text files
[0.2.0] - Previous
- Initial release with
googleSearchandgeminiChattools
🔗 Related Links
Gemini CLI MCP questions
How do I add Gemini CLI MCP to Claude Code?
Run claude mcp add mcp-gemini-cli -- npx -y @choplin/mcp-gemini-cli in your terminal. Add --scope user to make it available in every project.
How do I add Gemini CLI MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does Gemini CLI MCP provide?
It exposes 7 tools, including query, limit, sandbox, yolo, model.
Which Gemini model is used by default?
The default model used for tools is gemini-2.5-pro.