gemini-embedding-2-mcp

Un potente servidor del Protocolo de Contexto de Modelo (MCP) que utiliza gemini embedding 3 para transformar cualquier directorio local en un motor de búsqueda espacial ultrarrápido y visualmente consciente para agentes de IA.

GitHub

Prueba este MCPPatrocinado

Documentación

Un MCP de memoria local multimodal para agentes de IA impulsado por Gemini Embedding 2.

Conecta tus documentos locales, código, PDFs, imágenes, audio y video directamente a Claude, Cursor o VS Code usando el modelo gemini-embedding-2-preview de Google y una base de datos vectorial ChromaDB estrictamente local.

A diferencia de las herramientas RAG locales solo de texto, este servidor mantiene una capa de memoria local unificada para texto, páginas PDF visuales, imágenes, audio y video, y luego devuelve rutas de archivo exactas y contexto de página o fragmento a tu agente.

Por Qué Esto Es Diferente

Un espacio de embedding unificado entre modalidades: Busca código, PDFs, imágenes, audio y video desde la misma capa de memoria.
Persistencia local primero: Tu índice permanece en ~/.gemini_mcp_db, no en una base de datos vectorial alojada.
Recuperación amigable para agentes: Los resultados de búsqueda incluyen rutas exactas, tipos, modalidades y contexto consciente de página.
Cero configuración por defecto: El servidor utiliza protecciones integradas y valores predeterminados de indexación sensatos, por lo que la mayoría de los usuarios no necesitan un archivo de configuración.

Qué Puedes Preguntar

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.

✨ Características Clave

Característica	Descripción
🧠 Búsqueda Multimodal Unificada	Almacena texto, páginas PDF visuales, imágenes, audio y video en una memoria semántica local unificada para que una sola consulta pueda recuperar entre modalidades.
📄 Recuperación Visual de PDF	Renderiza PDFs página por página como imágenes para Gemini Embedding 2 mientras conserva el texto extraído para citas y contexto legibles por el agente.
🎯 Controles de Recuperación de Precisión	Admite filtros compactos para alcance, prefijo de ruta, tipo, extensión y modalidad, para que los agentes puedan buscar con precisión sin configuración pesada.
👀 Vista Previa Antes de Indexar	`preview_directory()` muestra lo que se indexará, agrupado por modalidad y motivo de omisión, antes de que se ejecute el escaneo.
🧾 Resultados Conscientes del Contexto	`get_result_context()` devuelve fragmentos o páginas vecinas para que los agentes puedan inspeccionar el material fuente exacto después de la búsqueda.
🛡️ Privacidad Local + Protecciones	Utiliza un almacén ChromaDB local, omite carpetas basura por defecto, bloquea escaneos de raíz peligrosos y maneja la deduplicación y la limpieza de archivos fantasma automáticamente.

🚀 Instalación y Configuración

Soportamos dos formas de ejecutar este servidor: Zero-Install (Recomendado) o Clon de Desarrollador Local. Asegúrate de tener uv instalado en tu máquina (pip install uv).

Método 1: Zero-Install (Recomendado)

Puedes indicarle a tu asistente de IA que ejecute el servidor directamente desde GitHub sin clonar el repositorio localmente. uvx actúa como npx para Python, descargando y almacenando en caché el servidor en un entorno efímero seguro automáticamente.

PyPI está configurado como el canal de distribución estable a largo plazo para versiones etiquetadas. Hasta que se complete la primera publicación en PyPI, usa la instalación con etiqueta de versión de Git fijada a continuación.

Para una instalación estable, fija una etiqueta de versión:

uvx --from git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@<release-tag> gemini-embedding-2-mcp

Ejemplo:

uvx --from git+https://github.com/AlaeddineMessadi/gemini-embedding-2-mcp-server.git@v1.2.1 gemini-embedding-2-mcp

Para una instalación edge, omite la etiqueta y sigue el estado más reciente de la rama main.

Una vez que la publicación en PyPI esté activa, el comando de instalación estable será:

uvx gemini-embedding-2-mcp-server

🔑 Obteniendo tu Clave de API de Gemini

Para alimentar el modelo de embedding, necesitas una clave de API gratuita de Google.

Ve a Google AI Studio.
Haz clic en Crear clave de API.
Copia la clave y úsala en tus configuraciones de cliente a continuación como GEMINI_API_KEY.

🔌 Guías de Conexión de Clientes

🤖 Claude Code (CLI)

Puedes adjuntar este servidor al CLI de Claude Code de forma nativa. Ejecuta el siguiente comando en tu 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

Abre tu archivo de configuración de Claude Desktop (generalmente ~/Library/Application Support/Claude/claude_desktop_config.json en macOS) y agrega:

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

Ve a Configuración > Funciones > MCP
Haz clic en + Agregar nuevo servidor MCP
Elige comando como tipo.
Nombre: gemini-embedding
Comando: 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)

Abre tu archivo ~/.codeium/windsurf/mcp_config.json y agrega:

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

Abre tu ~/.config/zed/settings.json y agrega el bloque de servidor MCP:

{
  "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 (con Cline / RooCode)

Abre ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json y agrega:

{
  "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"
      }
    }
  }
}

Método 2: Clon de Desarrollador Local

Si quieres modificar el código fuente:

# 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

(Si usas este método, puedes agregarlo directamente al CLI de Claude Code localmente ejecutando:)

claude mcp add gemini-embedding-local --env GEMINI_API_KEY="your-api-key" -- uv --directory "$(pwd)" run gemini-embedding-2-mcp

Método 3: Docker

Si necesitas un servidor MCP contenerizado para validación de registro o implementación, construye y ejecuta la imagen incluida:

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-server

El contenedor se comunica a través de E/S estándar como cualquier otro servidor MCP local y persiste los datos de ChromaDB en el volumen montado.

🛠️ Capacidades MCP Expuestas

Una vez conectado, tu asistente de IA obtiene instantáneamente las siguientes herramientas:

⚙️ Herramientas

index_directory(path: str, ignore: list = None): Escanea e incorpora formalmente una carpeta local completamente nueva en la base de datos. Admite de forma segura patrones comodín ignore.
preview_directory(path: str, ignore: list = None): Realiza una prueba de escaneo y ve qué se indexaría, agrupado por modalidad y motivo de omisión.
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): Ejecuta búsqueda semántica con filtros de recuperación compactos.
get_result_context(source: str, locator: str = None, window: int = 1): Obtén el contexto de fragmento o página cercano para un resultado previamente indexado.
list_indexed_directories(): Ve qué raíces de directorio ya conoce la IA.
sync_indexed_directories(): Fuerza automáticamente a la base de datos a encontrar archivos nuevos, actualizados o recientemente eliminados (fantasma) y limpia los vectores.
remove_directory_from_index(path: str): Limpia una trayectoria específica de vectores.

🔎 Filtros de Precisión

La herramienta de búsqueda principal se mantiene simple por defecto, pero admite algunos filtros de alto valor cuando necesitas exactitud:

scope: Limita las coincidencias a un alcance de directorio amplio, como /Users/me/work
path_prefix: Limita las coincidencias a un prefijo de ruta más exacto
types: Restringe por tipo de elemento almacenado, como text o pdf_visual_page
extensions: Restringe por extensión de archivo, como .pdf o .md
modalities: Restringe por modalidad, como text, pdf, image, audio o video

📊 Recursos

gemini://database-stats: ¡Observabilidad en tiempo real! Expone la escala exacta de los segmentos vectoriales dentro de ChromaDB directamente al contexto del asistente.