# 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`](https://github.com/googleapis/js-genai) SDK and the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-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](https://aistudio.google.com/apikey)

## Installation

```bash
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:

```bash
npm run build
```

## Connecting to an MCP client

### Claude Code

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

Verify it connected:

```bash
claude mcp get gemini-cortex
```

### Claude Desktop / other JSON-config clients

Add to your MCP config file:

```json
{
  "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

```bash
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](https://github.com/modelcontextprotocol/inspector) CLI against the built server:

```bash
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](LICENSE)