Gemini Context MCP server for AI agents

This Gemini Context MCP server leverages Gemini's capabilities for context management and caching, maximizing the value of its 2M token context window while providing efficient tools for managing large contexts in your AI applications.

Installation

Prerequisites

Node.js 18+ installed
Gemini API key (obtain from ai.google.dev)

Setup Instructions

# Clone the repository
git clone https://github.com/ogoldberg/gemini-context-mcp-server
cd gemini-context-mcp-server

# Install dependencies
npm install

# Copy environment variables example
cp .env.example .env

# Add your Gemini API key to .env file
# GEMINI_API_KEY=your_api_key_here

Starting the Server

# Build the server
npm run build

# Start the server
node dist/mcp-server.js

Using with MCP Clients

This server can be integrated with various MCP-compatible clients:

Quick Client Setup

Use the simplified client installation commands:

# Install and configure for Claude Desktop
npm run install:claude

# Install and configure for Cursor
npm run install:cursor

# Install and configure for VS Code
npm run install:vscode

Usage Examples

Basic Usage

Directly Using the Server

Start the server:
```
node dist/mcp-server.js
```

Test with the provided scripts:

# Test basic context management
node test-gemini-context.js

# Test caching features
node test-gemini-api-cache.js

Using in a Node.js Application

import { GeminiContextServer } from './src/gemini-context-server.js';

async function main() {
  // Create server instance
  const server = new GeminiContextServer();
  
  // Generate a response in a session
  const sessionId = "user-123";
  const response = await server.processMessage(sessionId, "What is machine learning?");
  console.log("Response:", response);
  
  // Ask a follow-up in the same session (maintains context)
  const followUp = await server.processMessage(sessionId, "What are popular algorithms?");
  console.log("Follow-up:", followUp);
}

main();

Advanced Usage

Custom Configurations

// Custom configuration
const config = {
  gemini: {
    apiKey: process.env.GEMINI_API_KEY,
    model: 'gemini-2.0-pro',
    temperature: 0.2,
    maxOutputTokens: 1024,
  },
  server: {
    sessionTimeoutMinutes: 30,
    maxTokensPerSession: 1000000
  }
};

const server = new GeminiContextServer(config);

Using the Caching System

// Create a cache for large system instructions
const cacheName = await server.createCache(
  'Technical Support System',
  'You are a technical support assistant for a software company...',
  7200 // 2 hour TTL
);

// Generate content using the cache
const response = await server.generateWithCache(
  cacheName,
  'How do I reset my password?'
);

// Clean up when done
await server.deleteCache(cacheName);

Configuration Options

Environment Variables

Create a .env file with these options:

# Required
GEMINI_API_KEY=your_api_key_here
GEMINI_MODEL=gemini-2.0-flash

# Optional - Model Settings
GEMINI_TEMPERATURE=0.7
GEMINI_TOP_K=40
GEMINI_TOP_P=0.9
GEMINI_MAX_OUTPUT_TOKENS=2097152

# Optional - Server Settings
MAX_SESSIONS=50
SESSION_TIMEOUT_MINUTES=120
MAX_MESSAGE_LENGTH=1000000
MAX_TOKENS_PER_SESSION=2097152
DEBUG=false

MCP Tools Integration

Available MCP Tools

Context Management Tools:
- generate_text - Generate text with context
- get_context - Get current context for a session
- clear_context - Clear session context
- add_context - Add specific context entries
- search_context - Find relevant context semantically
Caching Tools:
- mcp_gemini_context_create_cache - Create a cache for large contexts
- mcp_gemini_context_generate_with_cache - Generate with cached context
- mcp_gemini_context_list_caches - List all available caches
- mcp_gemini_context_update_cache_ttl - Update cache TTL
- mcp_gemini_context_delete_cache - Delete a cache

Connecting with Cursor

When used with Cursor, connect via the MCP configuration in settings.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "gemini-context" '{"command":"node","args":["dist/mcp-server.js"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "gemini-context": {
            "command": "node",
            "args": [
                "dist/mcp-server.js"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "gemini-context": {
            "command": "node",
            "args": [
                "dist/mcp-server.js"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect