zvec-mcp

Claude Code MCP服务器，为您的AI代理提供 本地矢量数据库 用于RAG知识检索和长期记忆——由实验.

______________________________________________________________________

它做什么

zvec-mcp作为一个模型上下文协议服务器通过stdio。一旦连接，Claude Code就会 11种新工具 用于存储、搜索和管理本地矢量数据库——完全离线，没有数据离开您的机器。

______________________________________________________________________

安装

先决条件

Python 3.10或更高版本
macOS、Linux或Windows
嵌入源（其中之一）：

- 像这样的本地服务器 LM 工作室, 奥拉玛，或虚拟大语言模型（推荐） - 句子变换器本地安装 - 一开放人工智能 API密钥

选项A——桌面扩展名（.mcpb）

最快的开始方式。下载预构建 .mcpb 文件并将其拖动到Claude Code中。

下载 zvec-mcp-0.1.0.mcpb 从最新版本
打开克劳德代码
去扩展标签
拖动 .mcpb 将文件放入放置区
在显示的设置中配置您的嵌入后端

注：这 .mcpb bundle默认为 超文本传输协议 嵌入后端，不包括句子转换器。要使用本地嵌入，请通过pip安装（选项B）。

选项B-pip安装

pip install zvec-mcp

这将安装 zvec-mcp 命令行入口点。要获取本地离线嵌入：

pip install zvec-mcp sentence-transformers

对于OpenAI嵌入：

pip install "zvec-mcp[openai]"

选项C——来源

git clone https://github.com/cluster2600/zvec-mcp.git
cd zvec-mcp

# Create a virtual environment and install
uv venv --python 3.10
uv pip install -e .

# Optional: local embeddings
uv pip install sentence-transformers

# Optional: OpenAI embeddings
uv pip install openai

______________________________________________________________________

使用Claude Code注册

安装后，您需要告诉Claude Code在哪里可以找到服务器。

用户范围（适用于所有项目）

claude mcp add-json zvec-mcp \
  '{"type":"stdio","command":"zvec-mcp","args":[],"env":{"ZVEC_MCP_DATA_DIR":"'"$HOME"'/.zvec-mcp","ZVEC_MCP_EMBEDDING":"http"}}' \
  --scope user

如果从源代码安装，请使用venv二进制文件的完整路径：

claude mcp add-json zvec-mcp \
  '{"type":"stdio","command":"'"$(pwd)"'/.venv/bin/zvec-mcp","args":[],"env":{"ZVEC_MCP_DATA_DIR":"'"$HOME"'/.zvec-mcp","ZVEC_MCP_EMBEDDING":"http"}}' \
  --scope user

项目范围（通过共享 `.mcp.json`)

创建或编辑 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "zvec-mcp": {
      "command": "zvec-mcp",
      "args": [],
      "env": {
        "ZVEC_MCP_DATA_DIR": "${HOME}/.zvec-mcp",
        "ZVEC_MCP_EMBEDDING": "http",
        "ZVEC_MCP_HTTP_URL": "http://127.0.0.1:1234/v1/embeddings",
        "ZVEC_MCP_HTTP_MODEL": "text-embedding-nomic-embed-text-v1.5@f16",
        "ZVEC_MCP_HTTP_DIM": "768"
      }
    }
  }
}

替换 "zvec-mcp" 如果命令不在您的 PATH （例如。 /path/to/zvec-mcp/.venv/bin/zvec-mcp).

验证

claude mcp list
# zvec-mcp: zvec-mcp  - ✓ Connected

您还可以在Claude Code内部通过以下方式进行检查：

“zvec-mcp的现状如何？”

克劳德会打电话给 zvec_status 工具并显示后端、维度和集合统计信息。

______________________________________________________________________

嵌入后端

zvec-mcp支持三个嵌入后端。您可以通过以下方式选择一个 ZVEC_MCP_EMBEDDING 环境变量。

HTTP——LM工作室/Ollama/vLLM

调用任何兼容OpenAI的 /v1/embeddings 终点。这是推荐 setup——它保持嵌入在本地，在GPU上运行（如果可用），并且不需要大量的Python依赖（使用Python的内置 urllib).

使用LM Studio进行设置：

安装 LM 工作室
下载嵌入模型（例如。 nomic-embed-text-v1.5)
启动本地服务器（LM Studio→ 开发者→ 启动服务器）
注意端口（默认 1234)和API密钥，如果您启用了身份验证

{
  "mcpServers": {
    "zvec-mcp": {
      "command": "zvec-mcp",
      "args": [],
      "env": {
        "ZVEC_MCP_EMBEDDING": "http",
        "ZVEC_MCP_HTTP_URL": "http://127.0.0.1:1234/v1/embeddings",
        "ZVEC_MCP_HTTP_MODEL": "text-embedding-nomic-embed-text-v1.5@f16",
        "ZVEC_MCP_HTTP_API_KEY": "your-api-key",
        "ZVEC_MCP_HTTP_DIM": "768"
      }
    }
  }
}

与Ollama一起设置：

安装奥拉玛
拉动嵌入模型： ollama pull nomic-embed-text
Ollama在港口服务 11434 默认情况下

{
  "env": {
    "ZVEC_MCP_EMBEDDING": "http",
    "ZVEC_MCP_HTTP_URL": "http://127.0.0.1:11434/v1/embeddings",
    "ZVEC_MCP_HTTP_MODEL": "nomic-embed-text",
    "ZVEC_MCP_HTTP_DIM": "768"
  }
}

重要提示： 这 ZVEC_MCP_HTTP_DIM 值必须与所选模型的输出维度匹配。常见值： 768 对于nomic嵌入文本， 384 对于所有MiniLM-L6-v2， 1024 对于BGE大。

本地-句子转换

跑 all-MiniLM-L6-v2 在您的机器上完全离线。384维，在Apple Silicon上使用MPS加速。不需要API密钥。

要求： pip install sentence-transformers （导入PyTorch，约500 MB）

{
  "env": {
    "ZVEC_MCP_EMBEDDING": "local"
  }
}

该模型在首次使用时会自动下载（约80 MB，缓存在 ~/.cache/torch/).

开放人工智能

使用OpenAI嵌入API。需要有效的API密钥。

{
  "env": {
    "ZVEC_MCP_EMBEDDING": "openai",
    "OPENAI_API_KEY": "sk-..."
  }
}

您可以自定义模型和尺寸：

{
  "env": {
    "ZVEC_MCP_EMBEDDING": "openai",
    "OPENAI_API_KEY": "sk-...",
    "ZVEC_MCP_OPENAI_MODEL": "text-embedding-3-large",
    "ZVEC_MCP_OPENAI_DIM": "3072"
  }
}

______________________________________________________________________

配置参考

所有设置都由环境变量驱动，通过 env MCP配置中的块。

变量	默认值	描述
`ZVEC_MCP_DATA_DIR`	`~/.zvec-mcp`	矢量数据库集合的根目录
`ZVEC_MCP_EMBEDDING`	`local`	嵌入后端： `local`, `openai`，或 `http`
`ZVEC_MCP_CHUNK_SIZE`	`512`	用于知识摄取的每个块的字符数
`ZVEC_MCP_CHUNK_OVERLAP`	`64`	连续块之间的重叠
HTTP后端
`ZVEC_MCP_HTTP_URL`	`http://127.0.0.1:1234/v1/embeddings`	OpenAI兼容的嵌入端点
`ZVEC_MCP_HTTP_MODEL`	`text-embedding-nomic-embed-text-v1.5@f16`	发送到端点的模型名称
`ZVEC_MCP_HTTP_API_KEY`	--	承载令牌（可选，取决于您的服务器）
`ZVEC_MCP_HTTP_DIM`	`768`	嵌入尺寸（必须与您的模型匹配）
OpenAI后端
`OPENAI_API_KEY`	--	使用OpenAI后端时需要
`ZVEC_MCP_OPENAI_MODEL`	`text-embedding-3-small`	OpenAI模型名称
`ZVEC_MCP_OPENAI_DIM`	`1536`	嵌入尺寸

______________________________________________________________________

工具参考

知识库（RAG）

工具	说明
`knowledge_ingest`	分块、嵌入和存储文本以供以后检索。接受 `text` 以及一个可选 `source` 标签。
`knowledge_ingest_file`	从磁盘读取文件并摄取其内容。接受文件 `path`.
`knowledge_search`	对摄入的文档进行语义搜索。接受a `query` 可选 `topk` （默认值5）。
`knowledge_delete_source`	从给定的块中删除所有块 `source`.
`knowledge_stats`	返回集合统计信息（单据数、嵌入维度、路径）。

记忆

工具	说明
`memory_remember`	储存一个事实、偏好或观察结果。接受 `text` 可选 `category` （默认值 `"general"`).
`memory_recall`	通过查询进行语义回忆。接受 `query`，可选 `topk` （默认值5），可选 `category` 过滤器。
`memory_forget`	按以下方式删除特定内存 `memory_id`.
`memory_forget_category`	删除a中的所有记忆 `category`.
`memory_stats`	返回内存存储统计信息。

状态

工具	说明
`zvec_status`	返回两个集合的服务器配置、嵌入后端和统计数据。

______________________________________________________________________

使用示例

注册后，您可以在与Claude Code的对话中自然地使用这些工具：

RAG的摄入文件：

“摄入以下内容 docs/api-reference.md 进入知识库。"

克劳德会打电话的 knowledge_ingest_file 沿着这条路。然后，您可以提出以下问题：

“身份验证流程是如何工作的？”

克劳德会打电话的 knowledge_search 检索相关块并在其答案中使用它们。

将项目上下文存储为内存：

“记住，这个项目使用PostgreSQL 16，主数据库名为 appdb."

克劳德会打电话的 memory_remember 与类别 "project"。稍后，在任何对话中：

“这个项目使用什么数据库？”

克劳德会打电话的 memory_recall 并检索存储的事实。

按类别组织记忆：

类别可帮助您组织不同类型的信息：

"preference" --编码风格、工具选择、命名约定
"project" -体系结构决策、数据库模式、API合同
"person" --团队成员角色、联系信息
"decision" --过去有理由的决定

“请记住，我们决定使用JWT进行身份验证而不是会话——主要原因是无状态扩展。”

克劳德把这个放在 "decision" 类别。

清理：

“从源中删除所有知识 docs/old-api.md." “忘记所有的记忆 project 类别。"

______________________________________________________________________

建筑

┌─────────────┐    stdio/JSON-RPC    ┌──────────────────────────┐
│ Claude Code  │◄───────────────────►│  zvec-mcp (FastMCP)      │
│   (client)   │                     │                          │
└─────────────┘                     │  ┌──────────┐            │
                                     │  │ knowledge │ chunk →   │
                                     │  │ manager   │ embed →   │
                                     │  │           │ store     │
                                     │  └─────┬────┘            │
                                     │        │                 │
                                     │  ┌─────▼────┐            │
                                     │  │   zvec    │ vector    │
                                     │  │collection │ search    │
                                     │  └─────┬────┘            │
                                     │        │                 │
                                     │  ┌─────▼────┐            │
                                     │  │  memory   │ remember  │
                                     │  │  manager  │ recall    │
                                     │  └──────────┘            │
                                     │                          │
                                     │  ┌──────────┐            │
                                     │  │embeddings│ local /   │
                                     │  │ (lazy)   │ openai /  │
                                     │  │          │ http      │
                                     │  └──────────┘            │
                                     └──────────────────────────┘

源布局

src/zvec_mcp/
├── server.py       # FastMCP server — 11 tools registered via @mcp.tool()
├── config.py       # Env-driven dataclass, reads all ZVEC_MCP_* variables
├── embeddings.py   # Lazy-loaded embedding singleton (local, OpenAI, or HTTP)
├── knowledge.py    # RAG pipeline: chunk → embed → upsert → query
└── memory.py       # Semantic memory: remember → recall → forget

RAG摄入是如何工作的

文本在句子边界处被分割成重叠的块（可配置大小和重叠）
每个块都通过配置的后端嵌入
块存储在zvec中 Collection 带字段： source, chunk_idx, text, created_at
块ID是内容寻址的(sha256(source:idx))--重新摄取相同的源更新

记忆是如何工作的

每个事实/观察都嵌入并存储了一个类别标签
内存ID是内容寻址的(sha256(text))--将同一文本存储两次是不可行的（重复数据删除）
Recall使用余弦相似度和可选的类别过滤
分类让你组织记忆（例如。 preference, project, person, decision)

______________________________________________________________________

数据存储

所有数据都存在于 ZVEC_MCP_DATA_DIR （默认值 ~/.zvec-mcp/):

~/.zvec-mcp/
├── knowledge/    # zvec collection for RAG chunks
└── memory/       # zvec collection for memories

集合在首次使用时自动创建。要重置所有内容，请删除目录：

rm -rf ~/.zvec-mcp

______________________________________________________________________

故障排除

服务器未显示为已连接

# Check MCP registration
claude mcp list

# Test the server directly (should print JSON-RPC on stdout)
zvec-mcp
# Or from source:
/path/to/zvec-mcp/.venv/bin/zvec-mcp

如果找不到该命令，请确保安装目录在您的 PATH，或在MCP配置中使用完整路径。

HTTP嵌入错误

连接被拒绝： 确保LM Studio/Ollama/vLLM服务器正在运行
401未经授权： 集 ZVEC_MCP_HTTP_API_KEY 到服务器的API密钥
尺寸不匹配： 如果在更改模型后搜索时出错，请删除数据目录(rm -rf ~/.zvec-mcp)并重新摄取——您不能在同一集合中混合不同维度的嵌入

首次运行时本地嵌入速度较慢

这 all-MiniLM-L6-v2 首次使用时下载型号（约80 MB）。后续运行从缓存加载(~/.cache/torch/).

`sentence-transformers` 未找到

本地后端需要 sentence-transformers.安装它：

pip install sentence-transformers

或者切换到 http 如果您正在运行LM Studio或Ollama，则使用后端。

重置数据库

要重新开始，请删除数据目录：

rm -rf ~/.zvec-mcp

下次使用时会自动重新创建集合。

______________________________________________________________________

构建.mcpb包

要从源代码构建桌面扩展，请执行以下操作：

# Install mcpb CLI
npm install -g @anthropic-ai/mcpb

# Install bundled dependencies (core only, no torch/sentence-transformers)
# IMPORTANT: let pip resolve versions — do NOT use --no-deps
pip install --target bundle/server/lib "mcp[cli]>=1.0.0" zvec numpy

# Copy zvec_mcp source into the bundle
cp -r src/zvec_mcp bundle/server/lib/zvec_mcp

# Strip caches (keep .dist-info — needed for importlib.metadata)
cd bundle/server/lib
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
find . -name "*.pyc" -delete 2>/dev/null
cd ../../..

# Validate manifest and pack
mcpb validate bundle/manifest.json
mcpb pack bundle/ zvec-mcp-0.1.0.mcpb

不要剥离 .dist-info 目录——MCP SDK使用 importlib.metadata.version("mcp") 在导入时，如果没有它们，将失败。不要使用 --no-deps --pydantic和pydantic核具有严格的版本耦合，必须一起解决。

______________________________________________________________________

依赖项

包	角色
实验	矢量数据库引擎
主控程序	模型上下文协议SDK（FastMCP）
句子变换器	本地嵌入（可选）
开放人工智能	OpenAI嵌入（可选）

许可证

阿帕奇-2.0

zvec MCP

快速接入

详细介绍

zvec-mcp

目录

它做什么

安装

先决条件

选项A——桌面扩展名（.mcpb）

选项B-pip安装

选项C——来源

使用Claude Code注册

用户范围（适用于所有项目）

项目范围（通过共享 .mcp.json)

验证

嵌入后端

HTTP——LM工作室/Ollama/vLLM

本地-句子转换

开放人工智能

配置参考

工具参考

知识库（RAG）

记忆

状态

使用示例

建筑

源布局

RAG摄入是如何工作的

记忆是如何工作的

数据存储

故障排除

服务器未显示为已连接

HTTP嵌入错误

首次运行时本地嵌入速度较慢

sentence-transformers 未找到

重置数据库

构建.mcpb包

依赖项

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

项目范围（通过共享 `.mcp.json`)

`sentence-transformers` 未找到