gemini-mcp

MCP server that wraps Gemini CLI for use with Claude Code and other MCP clients.

Use Gemini's large context window (1M tokens) and web search from within Claude Code.

Prerequisites

• Gemini CLI installed and authenticated
• Node.js 18+ or Bun

Installation

Via npm (recommended)

npm install -g @brenoxp/gemini-mcp

From source

git clone https://github.com/brenoxp/gemini-mcp.git
cd gemini-mcp
npm install
npm run build

Usage with Claude Code

Add to your Claude Code MCP configuration:

# If installed globally via npm
claude mcp add gemini-mcp -- gemini-mcp

# Or run directly with npx
claude mcp add gemini-mcp -- npx @brenoxp/gemini-mcp

# Or from source
claude mcp add gemini-mcp -- node /path/to/gemini-mcp/dist/index.js

Tools

gemini

Send a prompt directly to Gemini CLI.

Parameters:

• prompt (required): The prompt to send
• model: Gemini model to use (default: gemini-2.5-flash)
• allowed_tools: Comma-separated tools Gemini can use (e.g., web_search,shell)

gemini_with_agent_md

Send a prompt with an agent.md file as context. Useful for delegating tasks that need specific instructions.

Parameters:

• agent_md_path (required): Absolute path to agent.md file
• prompt (required): The prompt to send
• model: Override model (otherwise inferred from frontmatter)
• allowed_tools: Comma-separated tools Gemini can use

Model mapping from Claude agent.md frontmatter:

• haiku -> gemini-2.5-flash-lite
• sonnet -> gemini-2.5-flash
• opus -> gemini-2.5-pro

The tool automatically strips frontmatter from the agent.md before passing to Gemini.

Example prompts in Claude Code

Use the gemini tool to summarize this 500-page PDF: /path/to/large.pdf

Use gemini with web_search to find the latest React 19 features

Use gemini_with_agent_md with my research agent to investigate this topic

Why use this?

• Gemini has 1M token context - process huge files Claude can't handle in one shot
• Web search built into Gemini CLI
• Delegate cheap/simple tasks to Gemini, save Claude tokens for complex reasoning
• Run agents defined in agent.md files through Gemini

Development

# Run directly with Bun
bun run dev

# Type check
npm run typecheck

# Build for distribution
npm run build

License

MIT