Gemini Context MCP Server

How to use

You can use this MCP server with any MCP client that speaks the Model Context Protocol. Start a session, send messages, and rely on Gemini-powered context handling to track and retrieve relevant information across interactions. Use the built-in caching to reuse large system prompts and instructions, reducing token usage and costs.

Key capabilities you will leverage include creating and managing session-based contexts, semantically searching stored context, and using caches for large prompts or instructions. Contexts expire automatically, so you don’t have to manually clean up stale data.

How to install

Prerequisites you need before starting: - Node.js 18+ installed - Gemini API key (obtainable from the Gemini platform)

Step-by-step setup to get the server running locally: 1. Clone the project 2. Install dependencies 3. Copy and configure environment variables 4. Build the server 5. Start the server

# 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
# GEMINI_API_KEY=your_api_key_here

# Build the server
npm run build

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

Configuration and runtime notes

Configure environment variables to control model behavior and server limits. The following variables are commonly used in this setup:

# 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

Usage examples

Direct usage with a running server and test scripts demonstrates context management and caching features. You can also integrate the server into a Node.js application to keep a persistent session across messages.

# In Node.js, create a simple client to interact with the server
import { GeminiContextServer } from './src/gemini-context-server.js';

async function main() {
  const server = new GeminiContextServer();
  const sessionId = "user-123";
  const response = await server.processMessage(sessionId, "What is machine learning?");
  console.log("Response:", response);

  const followUp = await server.processMessage(sessionId, "What are popular algorithms?");
  console.log("Follow-up:", followUp);
}

main();

Security and maintenance notes

Store sensitive keys securely and avoid committing them to source control. The server includes automatic cleanup of expired sessions and caches to limit resource usage over time.

Development

You can build, run, and test locally while developing new features or integrations.

# Build TypeScript files
npm run build

# Run in development mode with auto-reload
npm run dev

# Run tests
npm test

generate_text

Generate text using the current session context and state.

get_context

Retrieve the current context for a specific session.

clear_context

Clear all context for a given session.

add_context

Add specific context entries to a session.

search_context

Find relevant context entries using semantic search.

mcp_gemini_context_create_cache

Create a cache for large contexts or prompts to reuse later.

mcp_gemini_context_generate_with_cache

Generate a response using a cached context to save on token usage.

mcp_gemini_context_list_caches

List all available caches.

mcp_gemini_context_update_cache_ttl

Update the time-to-live for a cache.

mcp_gemini_context_delete_cache

Delete a specific cache.