gemini-cortex-mcp

An MCP (Model Context Protocol) server that acts as a "second brain" for AI assistants — delegating tasks they can't do natively to Google Gemini: live web search, video/audio understanding, and summarizing massive files that would otherwise blow out your context window.

Built on the current @google/genai SDK and the official @modelcontextprotocol/sdk.

Tools

Tool	What it does
gemini_web_search	Answers a query using Gemini's Google Search grounding — a synthesized, up-to-date response with cited source URLs.
gemini_video_analyzer	Uploads a local video file and analyzes it against a specific prompt (e.g. "list every UI screen shown").
gemini_audio_analyzer	Uploads a local audio file and transcribes, summarizes, or analyzes tone — defaults to transcription + summary if no prompt is given.
gemini_massive_context	Sends large text files, logs, or PDFs (small text files inlined, everything else uploaded) to Gemini's large context window and returns a targeted, compressed summary.
gemini_prompt_engineer	Turns a raw task idea into a polished, structured "Master Prompt" for Claude, applying Anthropic's own prompt-engineering techniques (role definition, XML structuring, task-adaptive guidance) via Gemini acting as an expert meta-prompter.

Prerequisites

• Node.js >= 20
• A Gemini API key — get one free at aistudio.google.com/apikey

Installation

git clone https://github.com/atknony/gemini-cortex-mcp.git
cd gemini-cortex-mcp
npm install
cp .env.example .env

Open .env and set your key:

GEMINI_API_KEY=your_gemini_api_key_here

Build the server:

npm run build

Connecting to an MCP client

Claude Code

claude mcp add gemini-cortex -- node /absolute/path/to/gemini-cortex-mcp/dist/index.js

Verify it connected:

claude mcp get gemini-cortex

Claude Desktop / other JSON-config clients

Add to your MCP config file:

{
  "mcpServers": {
    "gemini-cortex": {
      "command": "node",
      "args": ["/absolute/path/to/gemini-cortex-mcp/dist/index.js"]
    }
  }
}

The server reads GEMINI_API_KEY from a .env file in its own directory at startup — no need to pass it through the client config. If the key is missing, the server exits immediately with a clear error rather than failing silently.

Configuration

All config is via environment variables (see .env.example). Only GEMINI_API_KEY is required.

Variable	Required	Default	Description
GEMINI_API_KEY	Yes	—	Your Gemini API key.
GEMINI_MODEL	No	—	Forces every tool to use this one model, overriding the per-tool defaults below.
GEMINI_MODEL_FLASH	No	gemini-flash-latest	Used by gemini_web_search and gemini_audio_analyzer.
GEMINI_MODEL_PRO	No	gemini-pro-latest	Used by gemini_video_analyzer, gemini_massive_context, and gemini_prompt_engineer.

Model names default to Google's rolling -latest aliases rather than a pinned, dated model, since specific model versions get retired roughly once a year.

Development

npm run dev         # tsx watch — runs TypeScript directly, restarts on save
npm run typecheck   # tsc --noEmit
npm run build        # compile to dist/

To smoke-test a tool end-to-end without a live MCP client session, use the MCP Inspector CLI against the built server:

npm run build
npx -y @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
npx -y @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call --tool-name gemini_web_search --tool-arg query="your question here"

Error handling

Every tool call is wrapped in centralized error handling that classifies Gemini API failures (rate limits, auth errors, transient server errors) into clear, actionable messages instead of crashing the server — including a specific warning when you hit a 429 rate limit or exhausted quota.

License

MIT