gemini-embedding-2-mcp

Um poderoso servidor Model Context Protocol (MCP) que usa o gemini embedding 3 para transformar qualquer diretório local em um mecanismo de busca espacial ultrarrápido e visualmente consciente para agentes de IA.

GitHub

Experimente este MCPPatrocinado

Documentação

Um MCP de memória local multimodal para agentes de IA alimentado pelo Gemini Embedding 2.

Conecte seus documentos locais, código, PDFs, imagens, áudio e vídeo diretamente ao Claude, Cursor ou VS Code usando o modelo gemini-embedding-2-preview do Google e um banco de dados vetorial ChromaDB estritamente local.

Diferente das ferramentas locais de RAG somente texto, este servidor mantém uma única camada de memória local entre texto, páginas visuais de PDF, imagens, áudio e vídeo, e retorna caminhos exatos de arquivos e contexto de página ou trecho de volta ao seu agente.

Por Que Isso é Diferente

Um único espaço de embeddings entre modalidades: Pesquise código, PDFs, imagens, áudio e vídeo a partir da mesma camada de memória.
Persistência local em primeiro lugar: Seu índice permanece em ~/.gemini_mcp_db, não em um banco de dados vetorial hospedado.
Recuperação amigável para agentes: Os resultados da busca incluem caminhos exatos, tipos, modalidades e contexto ciente de páginas.
Zero configuração por padrão: O servidor usa proteções integradas e padrões de indexação sensatos, então a maioria dos usuários não precisa de um arquivo de configuração.

O Que Você Pode Perguntar

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.

✨ Principais Recursos

Recurso	Descrição
🧠 Busca Multimodal Unificada	Armazena texto, páginas visuais de PDF, imagens, áudio e vídeo em uma única memória semântica local, para que uma única consulta possa recuperar entre modalidades.
📄 Recuperação Visual de PDF	Renderiza PDFs página por página como imagens para o Gemini Embedding 2, mantendo o texto extraído para citações e contexto legíveis pelo agente.
🎯 Controles de Recuperação de Precisão	Suporta filtros compactos para escopo, prefixo de caminho, tipo, extensão e modalidade, para que agentes possam pesquisar com precisão sem configuração pesada.
👀 Pré-visualização Antes da Indexação	`preview_directory()` mostra o que será indexado, agrupado por modalidade e motivo de pular, antes da varredura ser executada.
🧾 Resultados Cientes de Contexto	`get_result_context()` retorna trechos ou páginas vizinhas para que agentes possam inspecionar o material de origem exato após a busca.
🛡️ Privacidade Local + Proteções	Usa um armazenamento ChromaDB local, pula pastas de lixo por padrão, bloqueia varreduras perigosas na raiz e lida com deduplicação e limpeza automática de arquivos fantasmas.

🚀 Instalação e Configuração

Oferecemos duas maneiras de executar este servidor: Zero-Instalação (Recomendado) ou Clone Local para Desenvolvedores. Certifique-se de ter o uv instalado na sua máquina (pip install uv).

Método 1: Zero-Instalação (Recomendado)

Você pode apontar seu assistente de IA para executar o servidor diretamente do GitHub sem nunca clonar o repositório localmente. uvx funciona como npx para Python, baixando e armazenando em cache o servidor em um ambiente efêmero seguro automaticamente.

O PyPI está configurado como o canal de distribuição estável de longo prazo para versões com tags. Até que a primeira publicação no PyPI seja concluída, use a instalação fixada na tag de release do Git abaixo.

Para uma instalação estável, fixe em uma tag de release:

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

Exemplo:

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

Para uma instalação de ponta, omita a tag e acompanhe o estado mais recente do branch main.

Quando a publicação no PyPI estiver ativa, o comando de instalação estável se torna:

uvx gemini-embedding-2-mcp-server

🔑 Obtendo sua Chave de API do Gemini

Para alimentar o modelo de embeddings, você precisa de uma chave de API gratuita do Google.

Vá para Google AI Studio.
Clique em Criar chave de API.
Copie a chave e use-a nas configurações do seu cliente abaixo como GEMINI_API_KEY.

🔌 Guias de Conexão de Clientes

🤖 Claude Code (CLI)

Você pode anexar este servidor ao CLI do Claude Code nativamente. Execute o seguinte comando no seu 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

Abra o arquivo de configuração do Claude Desktop (geralmente ~/Library/Application Support/Claude/claude_desktop_config.json no macOS) e adicione:

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

Vá para Configurações > Recursos > MCP
Clique em + Adicionar novo servidor MCP
Escolha comando como o tipo.
Nome: 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)

Abra seu arquivo ~/.codeium/windsurf/mcp_config.json e adicione:

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

⚡ Editor Zed

Abra seu ~/.config/zed/settings.json e anexe o bloco do 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 (com Cline / RooCode)

Abra ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json e anexe:

{
  "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: Clone Local para Desenvolvedores

Se você quiser modificar o código-fonte:

# 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

(Se você usar este método, pode adicioná-lo diretamente ao CLI do Claude Code localmente executando:)

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

Se você precisar de um servidor MCP containerizado para validação de registro ou implantação, construa e execute a imagem incluída:

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

O contêiner se comunica por I/O padrão como qualquer outro servidor MCP local e persiste os dados do ChromaDB no volume montado.

🛠️ Capacidades MCP Expostas

Uma vez conectado, seu assistente de IA ganha instantaneamente as seguintes ferramentas:

⚙️ Ferramentas

index_directory(path: str, ignore: list = None): Escaneie e incorpore formalmente uma pasta local completamente nova no banco de dados. Suporta com segurança padrões curinga ignore.
preview_directory(path: str, ignore: list = None): Execute uma varredura de teste e veja o que seria indexado, agrupado por modalidade e motivo de pular.
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): Execute busca semântica com filtros de recuperação compactos.
get_result_context(source: str, locator: str = None, window: int = 1): Busque contexto de trecho ou página vizinha para um resultado previamente indexado.
list_indexed_directories(): Veja quais raízes de diretório o IA já conhece.
sync_indexed_directories(): Força automaticamente o banco de dados a encontrar arquivos novos, atualizados ou recentemente excluídos (fantasmas) e limpa vetores.
remove_directory_from_index(path: str): Limpa uma trajetória específica de vetores.

🔎 Filtros de Precisão

A ferramenta principal de busca permanece simples por padrão, mas suporta alguns filtros de alto valor quando você precisa de exatidão:

scope: Limite correspondências a um escopo de diretório amplo, como /Users/me/work
path_prefix: Limite correspondências a um prefixo de caminho mais exato
types: Restrinja por tipo de item armazenado, como text ou pdf_visual_page
extensions: Restrinja por extensão de arquivo, como .pdf ou .md
modalities: Restrinja por modalidade, como text, pdf, image, audio ou video

📊 Recursos

gemini://database-stats: Observabilidade em tempo real! Expõe a escala exata dos segmentos de vetores dentro do ChromaDB diretamente ao contexto do assistente.