目录
-
- 核心本地架构
- 一、前置环境安装（必装）
- [二、启动本地 Milvus 向量库](#二、启动本地 Milvus 向量库)
- 三、启动本地嵌入模型（纯离线）
- [四、本地构建 Claude-Context（核心服务）](#四、本地构建 Claude-Context（核心服务）)
-
- [1. 克隆代码](#1. 克隆代码)
- [2. 安装依赖 + 全量构建](#2. 安装依赖 + 全量构建)
- 五、纯本地环境配置（无任何云端密钥）
- 六、本地代码库索引（生成向量）
- [七、启动本地 MCP 服务](#七、启动本地 MCP 服务)
- [八、部署【本地 Claude-Code】+ 对接本地 MCP（核心步骤）](#八、部署【本地 Claude-Code】+ 对接本地 MCP（核心步骤）)
-
- [方式 1：官方本地版 Claude-Code（推荐）](#方式 1：官方本地版 Claude-Code（推荐）)
- [方式 2：开源本地 Claude-Code 替代](#方式 2：开源本地 Claude-Code 替代)
- 九、本地使用测试
- 十、离线使用（完全断网）
- 十一、常见问题
- 总结
（全程离线/内网可用，无任何云端依赖：本地向量库、本地嵌入模型、本地MCP、本地运行的 Claude-Code 客户端）
本方案严格适配 zilliztech/claude-context，100% 本地运行 ，专门对接你本地部署的 Claude-Code，不调用任何云端 API（Anthropic/Zilliz/OpenAI 全不用）。
核心本地架构
| 组件 | 本地替代方案 | 作用 |
|---|---|---|
| 向量数据库 | 本地 Milvus (Docker 单机) | 存储代码向量 |
| 文本嵌入模型 | 本地 Ollama 开源模型 | 代码向量化（完全离线） |
| MCP 索引服务 | 本地构建 claude-context |
代码检索/上下文提供 |
| AI 客户端 | 本地 Claude-Code | 本地使用，对接本地 MCP |
一、前置环境安装（必装）
仅需 4 个工具，全本地运行：
bash
# 1. 安装 Docker（运行 Milvus 向量库）
# Windows/macOS：Docker Desktop https://www.docker.com/
# Linux：
curl -fsSL https://get.docker.com | sh && sudo systemctl start docker
# 2. 安装 Node.js 22（必须 20~23 版本，不兼容 24+）
# macOS
brew install node@22
# Linux
curl -fsSL https://nodejs.org/dist/v22.11.0/node-v22.11.0-linux-x64.tar.xz | tar -xJ -C /usr/local --strip-components=1
# 3. 安装 pnpm（包管理器）
npm install -g pnpm
# 4. 安装 Ollama（本地嵌入模型，纯离线）
curl -fsSL https://ollama.com/install.sh | sh二、启动本地 Milvus 向量库
bash
# 下载配置文件
wget https://github.com/milvus-io/milvus/releases/download/v2.4.4/milvus-standalone-docker-compose.yml -O docker-compose.yml
# 后台启动（端口：19530）
docker compose up -d
# 验证运行状态
docker compose ps✅ 成功：显示 milvus-standalone 状态为 running
三、启动本地嵌入模型（纯离线）
bash
# 拉取开源嵌入模型（代码专用，离线可用）
ollama pull nomic-embed-text
# 验证服务（默认端口 11434）
curl http://localhost:11434✅ 成功：返回 Ollama is running
四、本地构建 Claude-Context（核心服务）
1. 克隆代码
bash
git clone https://github.com/zilliztech/claude-context.git
cd claude-context2. 安装依赖 + 全量构建
bash
# 安装依赖
pnpm install
# 构建核心模块（代码索引/搜索）
pnpm build:core
# 构建 MCP 服务（对接本地 Claude-Code）
pnpm build:mcp五、纯本地环境配置（无任何云端密钥）
在项目根目录 新建 .env 文件，直接复制以下内容，仅修改代码路径：
ini
# ===================== 纯本地配置 =====================
# 1. 本地 Ollama 嵌入模型（离线）
OPENAI_BASE_URL=http://localhost:11434/v1
OPENAI_API_KEY=ollama # 任意填写，本地无需真实key
EMBEDDING_MODEL=nomic-embed-text
# 2. 本地 Milvus 向量库
MILVUS_ADDRESS=http://localhost:19530
MILVUS_TOKEN=root:Milvus
# 3. 你要索引的【本地代码库路径】（必填！）
CODE_BASE_PATH=/Users/xxx/your-project # 改为你的代码文件夹路径六、本地代码库索引（生成向量）
bash
# 进入示例目录
cd examples/basic-usage
# 执行本地索引（扫描代码 → 生成向量 → 存入本地Milvus）
pnpm dev✅ 成功：终端输出 Indexed xx files（索引完成）
七、启动本地 MCP 服务
回到项目根目录，本地运行 MCP 服务（供本地 Claude-Code 调用）：
bash
# 根目录执行
node packages/mcp/dist/index.js✅ 成功：终端无报错，持续运行（保持终端开启）
八、部署【本地 Claude-Code】+ 对接本地 MCP（核心步骤）
方式 1：官方本地版 Claude-Code（推荐）
- 下载 本地 Claude-Code 客户端：https://claude.ai/download
- 安装后打开，进入设置 → MCP 服务器配置
- 新建 MCP 配置，直接复制以下内容：
json
{
"mcpServers": {
"claude-context-local": {
"command": "node",
"args": ["/Users/xxx/claude-context/packages/mcp/dist/index.js"],
"env": {
"OPENAI_BASE_URL": "http://localhost:11434/v1",
"OPENAI_API_KEY": "ollama",
"MILVUS_ADDRESS": "http://localhost:19530",
"MILVUS_TOKEN": "root:Milvus",
"CODE_BASE_PATH": "/Users/xxx/your-project"
}
}
}
}⚠️ 替换：args 为你的 claude-context 本地路径
方式 2：开源本地 Claude-Code 替代
用开源的 local-claude-code 本地客户端：
bash
# 启动本地开源版
docker run -p 8080:8080 local-claude-code配置 MCP 同上，对接本地 node 运行的 MCP 服务即可。
九、本地使用测试
在本地 Claude-Code 中输入指令，直接检索你的本地代码：
请检索我的项目中用户登录相关的代码✅ 成功：Claude-Code 会调用本地 MCP 服务，返回你本地代码库的相关片段。
十、离线使用（完全断网）
- 关闭网络
- 确保 Ollama、Milvus、MCP 服务均本地运行
- 打开本地 Claude-Code，直接使用
✅ 全程无外网请求，纯内网可用
十一、常见问题
- MCP 连接失败
- 检查 MCP 终端是否运行
- 确认路径填写正确（绝对路径）
- 索引为空
- 检查
CODE_BASE_PATH路径是否正确 - 确认代码文件夹有可索引的代码文件
- 检查
- Milvus 连接失败
- 确认 Docker 运行，端口 19530 未被占用
- Node 报错
- 降级到 Node.js 20~23 版本
总结
- 全程纯本地，无任何云端依赖，适配本地 Claude-Code
- 核心：本地 Milvus + 本地 Ollama + 本地构建 MCP
- 一键配置，离线/内网环境直接使用
- 本地 Claude-Code 可无缝检索你的本地代码库