快速配置 Claude Context MCP 服务器只需三步：1）选择一个嵌入提供商并设置对应的 API 密钥环境变量；2）在 AI 编程助手的 MCP 配置文件中，添加指向 @zilliz/claude-context-mcp 的 npx 启动命令，并将所需环境变量传入 env 字段；3）根据需要，可选调优后台同步、文件监听等高级参数。本文将逐步详解每个环节。

Claude Context MCP 服务器完全配置指南：支持 15+ AI 客户端

Claude Context 是一个 MCP (Model Context Protocol) 插件，它通过向量嵌入和 Milvus 向量数据库，为 Claude Code、Cursor 等 AI 编程助手提供强大的语义代码搜索能力。本文将提供一份完整的配置指南，帮助你将 Claude Context MCP 服务器集成到 15 种以上的 AI 编程助手中。

第一步：配置环境变量

Claude Context 的核心能力依赖于文本嵌入模型。配置过程首先需要选择一个嵌入提供商并设置其 API 密钥。

1. 选择并配置嵌入提供商

根据 packages/mcp/src/config.ts 中的 getDefaultModelForProvider 函数，系统为每个提供商设置了默认模型。你只需通过环境变量 EMBEDDING_PROVIDER 指定提供商，并设置对应的 API 密钥即可开始。

OpenAI (默认)

EMBEDDING_PROVIDER=OpenAI
OPENAI_API_KEY=sk-your-openai-api-key
# 可选：覆盖默认模型 `text-embedding-3-small`
# EMBEDDING_MODEL=text-embedding-3-large
# 可选：自定义 API 基础地址 (用于 Azure OpenAI 等)
# OPENAI_BASE_URL=https://your-custom-endpoint.com/v1

VoyageAI

EMBEDDING_PROVIDER=VoyageAI
VOYAGEAI_API_KEY=pa-your-voyageai-api-key
# 可选：覆盖默认模型 `voyage-code-3`
# EMBEDDING_MODEL=voyage-3-large

Gemini

EMBEDDING_PROVIDER=Gemini
GEMINI_API_KEY=your-gemini-api-key
# 可选：覆盖默认模型 `gemini-embedding-001`
# EMBEDDING_MODEL=gemini-embedding-002
# 可选：自定义 API 基础地址
# GEMINI_BASE_URL=https://your-custom-endpoint.com/v1beta

Ollama (本地/自托管)

EMBEDDING_PROVIDER=Ollama
# 指定 Ollama 上的嵌入模型名称
EMBEDDING_MODEL=nomic-embed-text
# 或者使用 OLLAMA_MODEL (优先级高于 EMBEDDING_MODEL)
# OLLAMA_MODEL=mxbai-embed-large
# 可选：指定 Ollama 服务地址 (默认为 http://127.0.0.1:11434)
# OLLAMA_HOST=http://localhost:11434
# 可选：指定嵌入维度以跳过运行时检测
# EMBEDDING_DIMENSION=768

2. 配置向量数据库

Claude Context 需要一个向量数据库来存储和检索代码向量。推荐使用 Zilliz Cloud 获取免费额度。

# 必需：Zilliz Cloud 的公共访问端点和 API 密钥
MILVUS_ADDRESS=your-zilliz-cloud-public-endpoint
MILVUS_TOKEN=your-zilliz-cloud-api-key

若只配置了 MILVUS_TOKEN，系统可以根据令牌自动解析出数据库地址。

3. 其他可选环境变量

EMBEDDING_BATCH_SIZE：嵌入批处理大小，根据模型吞吐量调整以优化性能，默认为 100。
CODE_CHUNKS_COLLECTION_NAME_OVERRIDE：在 Milvus/Zilliz 中为集合名称添加易读前缀，便于管理。

第二步：配置 MCP 客户端

完成环境变量设置后，需要将它们集成到你使用的 AI 编程助手中。以下列出了 15 种以上主流客户端的配置方法。

Claude Code

通过命令行直接添加 MCP 服务器：

claude mcp add claude-context \
  -e OPENAI_API_KEY=your-key \
  -e MILVUS_ADDRESS=your-address \
  -e MILVUS_TOKEN=your-token \
  -- npx @zilliz/claude-context-mcp@latest

更多管理命令请参考 Claude Code MCP 文档。

Cursor

将以下配置添加到 ~/.cursor/mcp.json 文件中（全局配置）或项目根目录的 .cursor/mcp.json 文件中（项目配置）。

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["-y", "@zilliz/claude-context-mcp@latest"],
      "env": {
        "EMBEDDING_PROVIDER": "OpenAI",
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

对于其他嵌入提供商，只需修改 EMBEDDING_PROVIDER 和对应的 API 密钥环境变量即可。

Windsurf / VS Code / Cline / Roo Code

这四种客户端的配置 JSON 结构几乎一致，区别在于配置文件位置不同。通用格式如下：

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

Windsurf: 添加到 Windsurf 的 MCP 设置中。
VS Code: 添加到 VS Code 兼容 MCP 的扩展设置中。
Cline: 编辑通过 Advanced MCP Settings 打开的 cline_mcp_settings.json 文件。
Roo Code: 编辑通过 Settings → MCP Servers → Edit Global Config 打开的 mcp_settings.json 文件。

Gemini CLI

编辑 ~/.gemini/settings.json 文件：

{
  "mcpServers": {
    "claude-context": {
      "command": "npx",
      "args": ["@zilliz/claude-context-mcp@latest"],
      "env": {
        "OPENAI_API_KEY": "your-openai-api-key",
        "MILVUS_TOKEN": "your-zilliz-cloud-api-key"
      }
    }
  }
}

OpenAI Codex CLI

编辑 ~/.codex/config.toml 文件（注意是 TOML 格式，顶级键为 mcp_servers）：

[mcp_servers.claude-context]
command = "npx"
args = ["@zilliz/claude-context-mcp@latest"]
env = { "OPENAI_API_KEY" = "your-openai-api-key", "MILVUS_TOKEN" = "your-zilliz-cloud-api-key" }

Qwen Code

编辑 ~/.qwen/settings.json 文件，配置格式与 Gemini CLI 相同。

Cherry Studio / Augment / Zencoder / Void

这些客户端支持通过图形界面或配置文件添加 MCP 服务器。

Cherry Studio / Augment / Zencoder: 在 GUI 中添加服务器，命令为 npx，参数为 ["-y", "@zilliz/claude-context-mcp@latest"]，并填写环境变量。
Void: 添加到 MCP 设置中，服务器名称（如 code-context）和环境变量键可能略有不同。

Claude Desktop

将通用 JSON 配置添加到 Claude Desktop 的 MCP 配置中即可。

LangChain/LangGraph

对于框架集成，请参考项目仓库中的 Python 示例。

通用方法 (任何兼容 MCP 的客户端)

所有 MCP 客户端都可以通过启动以下命令来集成 Claude Context：

npx @zilliz/claude-context-mcp@latest

确保将所需的环境变量（如 API 密钥）通过客户端支持的方式传递给该进程。

第三步：高级配置（可选）

你可以通过以下环境变量微调 Claude Context 的行为。

后台同步配置

默认情况下，MCP 服务器启动后和运行期间会进行周期性后台同步，以确保索引是最新的。

CLAUDE_CONTEXT_BACKGROUND_SYNC：设置为 false 可禁用启动和周期性的背景轮询。在单机运行多个 MCP 实例的 stdio 设置中，建议禁用此选项。

CLAUDE_CONTEXT_BACKGROUND_SYNC=false

CLAUDE_CONTEXT_SYNC_INTERVAL_MS：当 CLAUDE_CONTEXT_BACKGROUND_SYNC 为 true 时，此变量控制同步的间隔时间（毫秒）。默认为 300000（5分钟）。

CLAUDE_CONTEXT_SYNC_INTERVAL_MS=60000 # 设置为每分钟一次

触发文件监听器

除了周期性同步，服务器还会监听一个哨兵文件 ~/.context/.sync-trigger。修改此文件将触发一次即时的、带防抖（2秒）的重新索引。这允许外部工具（如 Claude Code 的 PostToolUse 钩子、编辑器保存钩子、CI 脚本）请求按需同步。

CLAUDE_CONTEXT_TRIGGER_WATCHER：设置为 false 可禁用此文件系统监听（适用于只读文件系统或沙箱环境）。默认为 true。

CLAUDE_CONTEXT_TRIGGER_WATCHER=true

示例：Claude Code 钩子配置

"hooks": {
  "PostToolUse": [
    { "matcher": "Edit|Write", "hooks": [
      { "type": "command", "command": "touch ~/.context/.sync-trigger" }
    ]}
  ]
}

FAQ

Q: 我在多个 AI 客户端中使用同一个代码库，需要为每个客户端都配置一遍 Claude Context 吗？ A: 不需要完全重复。核心的嵌入提供商和向量数据库环境变量（如 OPENAI_API_KEY, MILVUS_TOKEN）是共享的。你只需在每个客户端的 MCP 配置文件中，将这些相同的环境变量传入即可。所有客户端实例会连接到同一个向量数据库，但会通过代码库路径哈希维护独立的索引。

Q: 使用 Zilliz Cloud 的免费额度够用吗？ A: 对于个人开发者和中小型代码库完全足够。Zilliz Cloud 提供的免费套餐包含了足够的存储和计算资源。对于特别庞大的企业级代码库或极高并发场景，可能需要评估和升级套餐。索引的大小主要取决于代码片段的数量和嵌入向量的维度。

Q: 如果我想使用自托管的 Milvus 实例，该如何配置？ A: 只需将 MILVUS_ADDRESS 环境变量设置为你的 Milvus 实例的地址（例如 localhost:19530），并将 MILVUS_TOKEN 设置为对应的访问令牌（如果需要认证）。如果 Milvus 实例不需要认证，可以只设置地址。

Claude Context MCP 服务器完全配置指南：支持 15+ AI 客户端 #

第一步：配置环境变量 #

1. 选择并配置嵌入提供商 #

2. 配置向量数据库 #

3. 其他可选环境变量 #

第二步：配置 MCP 客户端 #

Claude Code #

Cursor #

Windsurf / VS Code / Cline / Roo Code #

Gemini CLI #

OpenAI Codex CLI #

Qwen Code #

Cherry Studio / Augment / Zencoder / Void #

Claude Desktop #

LangChain/LangGraph #

通用方法 (任何兼容 MCP 的客户端) #

第三步：高级配置（可选） #

后台同步配置 #

触发文件监听器 #

FAQ #