Gemini Embedding 2 Mcp

---

使用 Google 的 gemini-embedding-2-preview 模型和完全本地的 ChromaDB 向量数据库，将本地文档、代码、PDF、图像、音频和视频直接连接到 Claude、Cursor 或 VS Code。

与仅支持文本的本地 RAG 工具不同，此服务会在文本、PDF 可视页面、图像、音频和视频之间共用一个本地记忆层，然后将确切的文件路径以及页面或分块上下文返回给 Agent。

有何不同

• 跨模态统一嵌入空间：从同一记忆层搜索代码、PDF、图像、音频和视频。
• 本地优先持久化：索引保存在 ~/.gemini_mcp_db，而不是托管式向量数据库中。
• 面向 Agent 的检索：搜索结果包含确切路径、类型、模态以及按页面提供的上下文。
• 默认零配置：服务采用内置防护措施和合理的索引默认设置，大多数用户无需配置文件。

你可以这样提问

• 找到介绍我们设计令牌的 PDF 页面。
• 在我的图像库中搜索包含深色侧边栏仪表板的截图。
• 找到讨论价格变动的音频或视频片段。
• 仅在我的工作文档文件夹中搜索有关事件响应的入职说明。
• 提供结果 2 的周边上下文，以便我正确引用原始文件。

✨ 主要功能

功能	描述
🧠 统一多模态搜索	将文本、PDF 可视页面、图像、音频和视频存储在一个本地语义记忆中，单个查询即可跨模态检索。
📄 PDF 可视内容检索	按页将 PDF 渲染为图像，供 Gemini Embedding 2 处理，同时保留提取的文本，便于 Agent 阅读引用和上下文。
🎯 精确检索控制	支持按范围、路径前缀、类型、扩展名和模态进行简洁筛选，让 Agent 无需繁琐配置即可精准搜索。
👀 索引前预览	preview_directory() 会在扫描开始前，按模态和跳过原因显示将要索引的内容。
🧾 上下文感知结果	get_result_context() 会返回相邻分块或页面，让 Agent 在搜索后查看确切的源材料。
🛡️ 本地隐私与防护措施	使用本地 ChromaDB 存储，默认跳过无用文件夹，阻止危险的根目录扫描，并自动处理去重和幽灵文件清理。

---

🚀 安装与设置

我们支持两种运行此服务的方式：零安装（推荐）或本地开发者克隆。 请确保已在计算机上安装 uv（pip install uv）。

方法 1：零安装（推荐）

你可以让 AI 助手直接从 GitHub 运行服务，无需将仓库克隆到本地。uvx 类似于 Python 版的 npx，会自动在安全的临时环境中下载并缓存服务。

PyPI 已配置为带标签版本的长期稳定分发渠道。在首次完成 PyPI 发布之前，请使用下方固定 Git 发布标签的安装方式。

若要稳定安装，请固定到某个发布标签：

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

示例：

uvx --from git+https://github.com/AlaeddineMessadi/[email protected] gemini-embedding-2-mcp

若要体验前沿版本，请省略标签并跟踪最新的 main 分支状态。

PyPI 发布上线后，稳定安装命令将变为：

uvx gemini-embedding-2-mcp-server

🔑 获取 Gemini API 密钥

要运行嵌入模型，你需要一个 Google 提供的免费 API 密钥。

1. 前往 Google AI Studio。
2. 点击 Create API key。
3. 复制密钥，并在下方的客户端配置中将其用作 GEMINI_API_KEY。

---

🔌 客户端连接指南

🤖 Claude Code（CLI）

你可以原生地将此服务连接到 Claude Code CLI。 在终端中运行以下命令：

claude mcp add gemini-embedding-2-mcp \
  --env GEMINI_API_KEY="your-api-key-here" \
  -- uvx --from git+https://github.com/AlaeddineMessadi/[email protected] gemini-embedding-2-mcp

🦋 Claude Desktop

打开 Claude Desktop 配置文件（在 macOS 上通常为 ~/Library/Application Support/Claude/claude_desktop_config.json），并添加：

{
  "mcpServers": {
    "gemini-embedding-2-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AlaeddineMessadi/[email protected]",
        "gemini-embedding-2-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 Cursor IDE

1. 前往 Settings > Features > MCP
2. 点击 + Add new MCP server
3. 选择 command 作为类型。
4. 名称：gemini-embedding
5. 命令：GEMINI_API_KEY="your-api-key" uvx --from git+https://github.com/AlaeddineMessadi/[email protected] gemini-embedding-2-mcp

🏄‍♂️ Windsurf（Cascade）

打开 ~/.codeium/windsurf/mcp_config.json 文件并添加：

{
  "mcpServers": {
    "gemini-embedding-2-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AlaeddineMessadi/[email protected]",
        "gemini-embedding-2-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

⚡ Zed Editor

打开 ~/.config/zed/settings.json，并追加 MCP 服务配置块：

{
  "experimental.mcp": {
    "gemini-embedding-2-mcp": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AlaeddineMessadi/[email protected]",
        "gemini-embedding-2-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

💻 VS Code（搭配 Cline / RooCode）

打开 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json 并追加：

{
  "mcpServers": {
    "gemini-embedding": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/AlaeddineMessadi/[email protected]",
        "gemini-embedding-2-mcp"
      ],
      "env": {
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

---

方法 2：本地克隆用于开发

如果你想修改源代码：

# 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

（如果使用此方法，可以在本地运行以下命令，将其直接添加到 Claude Code CLI：）

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

---

方法 3：Docker

如果需要用于注册表验证或部署的容器化 MCP 服务，请构建并运行随附的映像：

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

该容器与其他本地 MCP 服务一样通过标准输入/输出进行通信，并将 ChromaDB 数据持久化到挂载卷中。

---

🛠️ 提供的 MCP 功能

连接后，你的 AI 助手将立即获得以下工具：

⚙️ 工具

• index_directory(path: str, ignore: list = None)：扫描一个全新的本地文件夹，并将其正式嵌入数据库。安全支持通配符 ignore 模式。
• preview_directory(path: str, ignore: list = None)：试运行扫描，并按模态和跳过原因分组，查看将要编入索引的内容。
• 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)：使用精简的检索筛选条件执行语义搜索。
• get_result_context(source: str, locator: str = None, window: int = 1)：获取先前编入索引的结果附近的文本块或页面上下文。
• list_indexed_directories()：查看 AI 已知的目录根路径。
• sync_indexed_directories()：自动强制数据库查找新增、更新或最近删除（幽灵）文件，并清理向量。
• remove_directory_from_index(path: str)：清除某个指定路径的向量。

🔎 精确筛选

主搜索工具默认保持简洁，但在需要精确搜索时，也支持一些高价值筛选条件：

• scope：将匹配范围限制在较大的目录范围内，例如 /Users/me/work
• path_prefix：将匹配范围限制为更精确的路径前缀
• types：按已存储的条目类型筛选，例如 text 或 pdf_visual_page
• extensions：按文件扩展名筛选，例如 .pdf 或 .md
• modalities：按模态筛选，例如 text、pdf、image、audio 或 video

📊 资源

• gemini://database-stats：实时可观测性！将 ChromaDB 中向量分段的确切规模直接提供给助手的上下文。

---

📚 技术文档

• 架构深入解析
• 终极多模态与 PDF RAG
• Agent 安全防护机制
• 使用案例
• 结果模型
• 发布

📜 许可证

MIT © Alaeddine Messadi