Claude Context 的安装配置看起来有几个变量（Embedding provider + 向量数据库 + 平台），但真正需要做的只有两步：获取两个 API Key（Embedding provider + Zilliz Cloud），然后在你的 AI 编程工具里加一行 MCP 配置。Claude Code 用户一条命令搞定；Cursor、Gemini CLI、Codex 用户在配置文件里加一段 JSON 即可。用 ~/.context/.env 全局配置文件可以避免在每个平台重复填写。

Claude Context 安装配置全指南：Claude Code / Cursor / Gemini CLI / Codex

本文聚焦「怎么装、怎么配」，不展开索引原理。如果你想先了解 Claude Context 是什么、能带来什么改变，可以先看 Claude Context 总览。

前提条件：两个 API Key

Claude Context 需要两类服务才能工作：

服务	作用	怎么获取
Embedding Provider	把代码片段转成向量	OpenAI / VoyageAI / Gemini / Ollama
向量数据库	存储和检索向量	Zilliz Cloud（免费）或本地 Milvus

Embedding Provider 选型

你只需要选一个，不需要全都配置。

Provider	适合谁	推荐模型	说明
OpenAI	大多数用户（默认选项）	`text-embedding-3-small`	配置最简单，需要 OpenAI 付费账户
VoyageAI	代码密集型项目	`voyage-code-3`	专门为代码理解优化的 Embedding 模型
Gemini	已有 Google API Key 的用户	`gemini-embedding-001`	多语言支持好，有免费额度
Ollama	想完全本地运行	`nomic-embed-text`	不需要外部 API，但要自己管理资源

OpenAI 是配置最简单的选项，大部分教程和文档示例都以它为基准。如果你已经有 OpenAI API Key，直接选 OpenAI 省事。

如果你想完全本地部署（不把代码发到云端），选 Ollama + 本地 Milvus。这部分细节可以参考常见问题与排查指南里的本地部署方案。

向量数据库：Zilliz Cloud

Zilliz Cloud 是官方推荐的托管 Milvus 服务，注册后免费获得一个 Serverless 集群。

注册流程：

注册 Zilliz Cloud
创建集群后，在控制台获取两个值：
- Public Endpoint（形如 https://in01-xxx.api.gcp-us-west1.zillizcloud.com）
- API Key（个人密钥）

把这两个值记下来，后面配置要用到。

各平台安装命令

Claude Code（推荐，一行命令）

bash

claude mcp add claude-context \
  -e OPENAI_API_KEY=sk-你的OpenAI-API-Key \
  -e MILVUS_ADDRESS=你的Zilliz-Public-Endpoint \
  -e MILVUS_TOKEN=你的Zilliz-API-Key \
  -- npx @zilliz/claude-context-mcp@latest

配置完成后，开启新会话即可使用。验证方式：在 Claude Code 中说 Check the indexing status，AI 会调用 Claude Context 工具返回状态信息。

如果使用其他 Embedding Provider：

bash

# VoyageAI
claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=VoyageAI \
  -e VOYAGEAI_API_KEY=pa-你的VoyageAI-Key \
  -e MILVUS_TOKEN=你的Zilliz-Token \
  -- npx @zilliz/claude-context-mcp@latest

# Gemini
claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=Gemini \
  -e GEMINI_API_KEY=你的Gemini-Key \
  -e MILVUS_TOKEN=你的Zilliz-Token \
  -- npx @zilliz/claude-context-mcp@latest

# Ollama（本地）
claude mcp add claude-context \
  -e EMBEDDING_PROVIDER=Ollama \
  -e EMBEDDING_MODEL=nomic-embed-text \
  -e OLLAMA_HOST=http://127.0.0.1:11434 \
  -e MILVUS_ADDRESS=127.0.0.1:19530 \
  -e MILVUS_TOKEN=你的Milvus-Token \
  -- npx @zilliz/claude-context-mcp@latest

Cursor

打开 Settings → Cursor Settings → MCP → Add new global MCP server，在 ~/.cursor/mcp.json 中添加：

json

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "sk-你的OpenAI-API-Key",
        "MILVUS_TOKEN": "你的Zilliz-API-Key"
      }
    }
  }
}

如果使用其他 provider，加 "EMBEDDING_PROVIDER": "VoyageAI"（或 Gemini、Ollama）和对应的 Key。

Gemini CLI

编辑 ~/.gemini/settings.json：

json

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "sk-你的OpenAI-API-Key",
        "MILVUS_TOKEN": "你的Zilliz-API-Key"
      }
    }
  }
}

重启 Gemini CLI 生效。

Codex CLI

编辑 ~/.codex/config.toml：

toml

[mcp_servers.claude-context]
command = "npx"
args = ["@zilliz/claude-context-mcp@latest"]
env = { "OPENAI_API_KEY" = "sk-你的Key", "MILVUS_TOKEN" = "你的Zilliz-Token" }
startup_timeout_ms = 20000

注意 Codex 用的是 mcp_servers（下划线），不是 mcpServers（驼峰）。startup_timeout_ms 建议调高到 20 秒，避免 npx 下载超时。

Windsurf / VS Code / Claude Desktop

这三个平台配置格式相同，在对应 MCP 设置中添加：

json

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "sk-你的Key",
        "MILVUS_TOKEN": "你的Zilliz-Token"
      }
    }
  }
}

全局配置文件：避免重复填写

Claude Context 支持全局配置文件 ~/.context/.env，好处是一次配置、所有平台共用。

bash

mkdir -p ~/.context
cat > ~/.context/.env << 'EOF'
EMBEDDING_PROVIDER=OpenAI
OPENAI_API_KEY=sk-你的Key
EMBEDDING_MODEL=text-embedding-3-small
MILVUS_TOKEN=你的Zilliz-Token
EOF

配好后，Cursor、Windsurf 等平台的 MCP 配置可以简化为不含 Key 的形式：

json

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"]
    }
  }
}

环境变量优先级从高到低：

进程环境变量（平台 MCP 配置里的 env 字段）
~/.context/.env 全局文件
默认值

如果你在某个平台单独设了 Key，它会覆盖全局配置。

高级配置选项

自定义文件处理

你可以在全局配置或平台 env 中设置：

bash

# 额外索引的文件扩展名（Vue、Svelte、Astro 等）
CUSTOM_EXTENSIONS=.vue,.svelte,.astro

# 额外忽略的文件/目录
CUSTOM_IGNORE_PATTERNS=temp/**,*.backup,private/**

调大 Embedding 批次大小

bash

EMBEDDING_BATCH_SIZE=512

默认值 100，如果你的 Embedding Provider 吞吐较高（比如 VoyageAI），可以调大加速索引。

切换代码分割器

bash

# ast: 语法感知切块（推荐，更精确）
# langchain: 基于字符切块（更快，但不够精确）
SPLITTER_TYPE=ast

自定义集合名称前缀

如果你的 Zilliz Cloud 里有多个代码库索引，可以加前缀区分：

bash

CODE_CHUNKS_COLLECTION_NAME_OVERRIDE=my_project

验证配置

配置完成后，开启新会话（Claude Code 需要新会话才能加载新的 MCP），然后执行：

Index this codebase — 启动索引
Check the indexing status — 查看状态
Find functions that handle user authentication — 测试搜索

如果状态显示 indexed，搜索返回了相关结果，说明配置成功。

遇到问题可以参考常见问题与排查指南。

FAQ

Q: OpenAI 和 VoyageAI 怎么选？ A: 如果你已经有 OpenAI API Key 并且只是想快速体验，用 OpenAI。如果你的项目是纯代码仓库（前端/后端框架），VoyageAI 的 voyage-code-3 专门为代码优化，理论上对代码语义理解更好。但实际差异没有想象中大，先选 OpenAI 把体验跑通更重要。

Q: 我的代码会上传到哪里？ A: 使用 Zilliz Cloud + 云端 Embedding 时，代码片段会发到 Embedding Provider 做向量化，向量存到 Zilliz Cloud。如果你用 Ollama + 本地 Milvus，所有处理都在本地完成。需要代码不出网的团队，必须选本地方案。

Q: 可以多个项目共用一个 Zilliz Cloud 集群吗？ A: 可以。Claude Context 会为每个代码库路径生成独立的集合名称（带路径哈希），不会互相污染。

Claude Context 安装配置全指南：Claude Code / Cursor / Gemini CLI / Codex ​

前提条件：两个 API Key ​

Embedding Provider 选型 ​

向量数据库：Zilliz Cloud ​

各平台安装命令 ​

Claude Code（推荐，一行命令） ​

Cursor ​

Gemini CLI ​

Codex CLI ​

Windsurf / VS Code / Claude Desktop ​

全局配置文件：避免重复填写 ​

高级配置选项 ​

自定义文件处理 ​

调大 Embedding 批次大小 ​

切换代码分割器 ​

自定义集合名称前缀 ​

验证配置 ​

FAQ ​

Claude Context 安装配置全指南：Claude Code / Cursor / Gemini CLI / Codex

前提条件：两个 API Key

Embedding Provider 选型

向量数据库：Zilliz Cloud

各平台安装命令

Claude Code（推荐，一行命令）

Cursor

Gemini CLI

Codex CLI

Windsurf / VS Code / Claude Desktop

全局配置文件：避免重复填写

高级配置选项

自定义文件处理

调大 Embedding 批次大小

切换代码分割器

自定义集合名称前缀

验证配置

FAQ