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

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.

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