Gemini Embedding 2 MCP Server
Allows connection to Windsurf (Cascade) for searching and retrieving local multimodal documents.
Uses Google's Gemini Embedding 2 model for multimodal embedding and search.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gemini Embedding 2 MCP Server find PDF pages about design tokens"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Connect your local documents, code, PDFs, images, audio, and video directly to Claude, Cursor, or VS Code using Google's gemini-embedding-2-preview model and a strictly local ChromaDB vector database.
Unlike text-only local RAG tools, this server keeps one local memory layer across text, visual PDF pages, images, audio, and video, then returns exact file paths and page or chunk context back to your agent.
Why This Is Different
One embedding space across modalities: Search code, PDFs, images, audio, and video from the same memory layer.
Local-first persistence: Your index stays in
~/.gemini_mcp_db, not in a hosted vector database.Agent-friendly retrieval: Search results include exact paths, types, modalities, and page-aware context.
Zero-config by default: The server uses built-in guardrails and sensible indexing defaults so most users do not need a config file.
Related MCP server: HKC Memory Server
What You Can Ask
Find the PDF page that explains our design tokens.Search my image library for screenshots of dashboards with dark sidebars.Find the audio or video clip where we talked about pricing changes.Search only my work docs folder for onboarding notes about incident response.Give me the surrounding context for result 2 so I can cite the original file correctly.
โจ Key Features
Feature | Description |
๐ง Unified Multimodal Search | Stores text, visual PDF pages, images, audio, and video in one local semantic memory so a single query can retrieve across modalities. |
๐ Visual PDF Retrieval | Renders PDFs page-by-page as images for Gemini Embedding 2 while retaining extracted text for agent-readable citations and context. |
๐ฏ Precision Retrieval Controls | Supports compact filters for scope, path prefix, type, extension, and modality so agents can search precisely without heavy configuration. |
๐ Preview Before Indexing |
|
๐งพ Context-Aware Results |
|
๐ก๏ธ Local Privacy + Guardrails | Uses a local ChromaDB store, skips junk folders by default, blocks dangerous root scans, and handles deduplication and ghost-file cleanup automatically. |
๐ Installation & Setup
We support two ways to run this server: Zero-Install (Recommended) or Local Developer Clone.
Make sure you have uv installed on your machine (pip install uv).
Method 1: Zero-Install (Recommended)
You can point your AI assistant to run the server directly from GitHub without ever cloning the repository locally. uvx acts like npx for Python, downloading and caching the server in a secure ephemeral environment automatically.
PyPI is configured as the long-term stable distribution channel for tagged releases. Until the first PyPI publish completes, use the pinned Git release-tag install below.
For a stable install, pin to a release tag:
uvx --from git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@<release-tag> gemini-embedding-2-mcpExample:
uvx --from git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@v1.2.1 gemini-embedding-2-mcpFor an edge install, omit the tag and track the latest main branch state.
Once PyPI publishing is live, the stable install command becomes:
uvx gemini-embedding-2-mcp-server๐ Getting your Gemini API Key
To power the embedding model, you need a free API key from Google.
Go to Google AI Studio.
Click Create API key.
Copy the key and use it in your client configurations below as
GEMINI_API_KEY.
๐ Client Connection Guides
๐ค Claude Code (CLI)
You can attach this server to the Claude Code CLI natively. Run the following command in your terminal:
claude mcp add gemini-embedding-2-mcp \
--env GEMINI_API_KEY="your-api-key-here" \
-- uvx --from git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@v1.2.1 gemini-embedding-2-mcp๐ฆ Claude Desktop
Open your Claude Desktop config file (usually ~/Library/Application Support/Claude/claude_desktop_config.json on macOS) and add:
{
"mcpServers": {
"gemini-embedding-2-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@v1.2.1",
"gemini-embedding-2-mcp"
],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}๐ป Cursor IDE
Go to Settings > Features > MCP
Click + Add new MCP server
Choose command as the type.
Name:
gemini-embeddingCommand:
GEMINI_API_KEY="your-api-key" uvx --from git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@v1.2.1 gemini-embedding-2-mcp
๐โโ๏ธ Windsurf (Cascade)
Open your ~/.codeium/windsurf/mcp_config.json file and add:
{
"mcpServers": {
"gemini-embedding-2-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@v1.2.1",
"gemini-embedding-2-mcp"
],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}โก Zed Editor
Open your ~/.config/zed/settings.json and append the MCP server block:
{
"experimental.mcp": {
"gemini-embedding-2-mcp": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@v1.2.1",
"gemini-embedding-2-mcp"
],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}๐ป VS Code (with Cline / RooCode)
Open ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json and append:
{
"mcpServers": {
"gemini-embedding": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@v1.2.1",
"gemini-embedding-2-mcp"
],
"env": {
"GEMINI_API_KEY": "your-api-key-here"
}
}
}
}Method 2: Local Developer Clone
If you want to modify the source code:
# 1. Clone the repository
git clone https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git
cd gemini-embedding-2-mcp-server
# 2. Install dependencies
uv sync(If you use this method, you can add it directly to Claude Code CLI locally by running:)
claude mcp add gemini-embedding-local --env GEMINI_API_KEY="your-api-key" -- uv --directory "$(pwd)" run gemini-embedding-2-mcpMethod 3: Docker
If you need a containerized MCP server for registry validation or deployment, build and run the included image:
docker build -t gemini-embedding-2-mcp-server .
docker run --rm -i \
-e GEMINI_API_KEY="your-api-key-here" \
-v "$HOME/.gemini_mcp_db:/root/.gemini_mcp_db" \
gemini-embedding-2-mcp-serverThe container communicates over standard I/O like any other local MCP server and persists ChromaDB data in the mounted volume.
๐ ๏ธ Exposed MCP Capabilities
Once connected, your AI assistant instantly gains the following tools:
โ๏ธ Tools
index_directory(path: str, ignore: list = None): Scan and formally embed a completely new local folder into the DB. Safely supports wildcardignorepatterns.preview_directory(path: str, ignore: list = None): Dry-run a scan and see what would be indexed, grouped by modality and skip reason.search_my_documents(query: str, limit: int, scope: str = None, types: list[str] = None, path_prefix: str = None, extensions: list[str] = None, modalities: list[str] = None): Run semantic search with compact retrieval filters.get_result_context(source: str, locator: str = None, window: int = 1): Fetch nearby chunk or page context for a previously indexed result.list_indexed_directories(): See which directory roots the AI already knows about.sync_indexed_directories(): Automatically forces the DB to find new, updated, or recently deleted (ghost) files and cleans up vectors.remove_directory_from_index(path: str): Clears a specific trajectory of vectors.
๐ Precision Filters
The main search tool stays simple by default, but supports a few high-value filters when you need exactness:
scope: Limit matches to a broad directory scope such as/Users/me/workpath_prefix: Limit matches to a more exact path prefixtypes: Restrict by stored item type such astextorpdf_visual_pageextensions: Restrict by file extension such as.pdfor.mdmodalities: Restrict by modality such astext,pdf,image,audio, orvideo
๐ Resources
gemini://database-stats: Real-time observability! Exposes the exact scale of the vector segments inside ChromaDB directly to the assistant's context.
๐ Technical Documentation
๐ License
MIT ยฉ Alaeddine Messadi
Available Tools
7 toolsget_result_contextC
Returns nearby chunks or pages for a previously indexed result.
Inputs: source (required), locator, window. Returns: result
index_directoryB
Scans a local directory, extracts text from files (PDF, DOCX, TXT, MD) AND raw video/audio/image bytes, generates semantic embeddings using Gemini 2 and stores them for searching.
Args: directory_path: Absolute path to the directory. ignore: Optional list of glob patterns to ignore (e.g., [".log", "drafts", "temp"]).
Inputs: directory_path (required), ignore. Returns: result
list_indexed_directoriesA
Lists indexed parent directories known to the database.
Inputs: no named parameters. Returns: result
preview_directoryB
Summarizes what would be indexed before the server performs a full scan.
Inputs: directory_path (required), ignore. Returns: result
remove_directory_from_indexC
Removes all documents and images belonging to a specific directory path from the index.
Inputs: directory_path (required). Returns: result
search_my_documentsC
Performs a semantic search over your previously indexed local documents AND images using the Gemini 2 Embedding model.
Inputs: query (required), limit, scope, types, +3 more. Returns: result
sync_indexed_directoriesA
Auto-updates existing folders. It finds all unique parent directories of currently indexed files and re-indexes them to capture new or modified files.
Inputs: no named parameters. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogโฆ
TDQS
Scored across 7 tools
Each tool targets a distinct operation: indexing, previewing, listing, searching, context retrieval, removal, and syncing. No functional overlap exists.
All tool names follow a consistent verb_noun pattern in snake_case, e.g., index_directory, list_indexed_directories, search_my_documents. The pattern is uniform and predictable.
With 7 tools, the server covers the essential workflows for local embedding and retrieval without excess or deficiency. The count fits well with the domain scope.
Provides a full lifecycle: create (index_directory), read (search, get_result_context, list), update (sync_indexed_directories), delete (remove_directory_from_index), plus a dry-run preview. No obvious gaps.
Maintenance
Related MCP Connectors
An MCP memory server. One memory your agents share โ across models, devices and apps.
Hosted memory for AI agents over MCP. One memory shared by all your agents.
Persistent memory, knowledge graph, task management and more for AI agents via MCP.
Persistent personal memory for AI assistants โ save, search, and recall across every MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA self-hosted, multi-context memory server that enables AI agents to search and retrieve information from local documents and crawled websites via MCP tools. It runs fully offline using Postgres and Ollama to provide secure, private knowledge management and retrieval-augmented generation.2MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server for managing persistent AI memory using hybrid search (keyword + semantic vector) with SQLite storage and offline-first local embeddings.-
- AlicenseNot gradedqualityDmaintenanceA lightweight, local-first MCP memory server for LLM agents that enables storing, searching, and retrieving agent memories with zero external dependencies.1MIT
- AlicenseAqualityBmaintenanceMCP server for persistent, cross-session, local-first memory for AI agents, storing memories as Markdown files with SQLite indexing for hybrid search.24Apache 2.0