zvec MCP

MCP数据服务

提供方 cluster2600

数据服务 stdio · 本地进程 无需鉴权 社区 / 第三方 Claude
查看接入方式

zvec-mcp是一个为AI代理提供本地向量数据库服务的工具,支持RAG知识检索和长期记忆功能,完全离线运行。

一句话选型结论

按资料字段整理

zvec MCP 属于数据服务类 MCP 服务器,stdio · 本地进程,无需鉴权,可直接接入 Claude,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类数据服务 传输方式stdio · 本地进程 鉴权无需鉴权 部署方式本地部署
GitHub 星标 1 仓库热度,无公开仓库时显示未标注
工具数 11 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

数据服务
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量11暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

支持客户端

适用场景

向量数据库Python本地部署RAG知识检索长期记忆AI代理

安装与配置

stdio · 本地进程 无需鉴权
客户端在本机拉起子进程,数据不出本机
pip install zvec-mcp

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 11 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
数据库查询

用自然语言查库、取数,不用手写 SQL。

数据同步与清洗

把多来源数据拉到一处做整理。

报表取数

按口径快速拉出统计结果。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 11 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。
  • 已适配 Claude,换客户端不用重新研究配置。
  • 资料标注无需鉴权,装好就能连。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在数据服务场景里让模型直接调用外部能力的人。
  • 已经在用 Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
zvec MCP当前 11 stdio · 本地进程 本地部署 有 2026-05-17
Memory 9d25f64e 9 未标注 未标注 无 2026-05-17
Getzep MCP 9 stdio · 本地进程 本地部署 有 2026-05-17
anything-llm 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Prisma MCP Server 未标注 stdio · 本地进程 本地部署 有 2026-05-17
Astr Bot 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

数据服务
字段来自项目仓库与公开索引,中文说明由本站标注
提供方cluster2600上游标注的维护方 cluster2600
分类数据服务本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式无需鉴权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

15.4 KB
来自项目仓库与上游目录的原文,未做删改

zvec-mcp

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


目录

  • 它做什么
  • 安装
  • 选项A——桌面扩展名(.mcpb)
  • 选项B-pip安装
  • 选项C——来源
  • 使用Claude Code注册
  • 用户范围
  • 项目范围
  • 验证
  • 嵌入后端
  • HTTP——LM工作室/Ollama/vLLM
  • 本地-句子转换
  • 开放人工智能
  • 配置参考
  • 工具参考
  • 知识库(RAG)
  • 记忆
  • 状态
  • 使用示例
  • 建筑
  • 数据存储
  • 故障排除
  • 许可证

它做什么

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


安装

先决条件

  • Python 3.10或更高版本
  • macOS、Linux或Windows
  • 嵌入源(其中之一):
  • 像这样的本地服务器 LM 工作室, 奥拉玛,或 虚拟大语言模型 (推荐)
  • 句子变换器 本地安装
  • 一 开放人工智能 API密钥

选项A——桌面扩展名(.mcpb)

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

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

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

选项B-pip安装```bash

pip install zvec-mcp


这将安装 `zvec-mcp` 命令行入口点。要获取本地离线嵌入:```bash
pip install zvec-mcp sentence-transformers

对于OpenAI嵌入:```bash
pip install "zvec-mcp[openai]"


### 选项C——来源```bash
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在哪里可以找到服务器。

用户范围(适用于所有项目)```bash

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二进制文件的完整路径:```bash
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 在项目根目录中:```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`).

### 验证```bash
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进行设置:

  1. 安装 LM 工作室
  2. 下载嵌入模型(例如。 nomic-embed-text-v1.5)
  3. 启动本地服务器(LM Studio→ 开发者→ 启动服务器)
  4. 注意端口(默认 1234)和API密钥,如果您启用了身份验证```json
    {
    "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一起设置:**

1. 安装 奥拉玛
1. 拉动嵌入模型: `ollama pull nomic-embed-text`
1. Ollama在港口服务 `11434` 默认情况下```json
{
"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)```json
{
"env": {
"ZVEC_MCP_EMBEDDING": "local"
}
}


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

### 开放人工智能

使用OpenAI嵌入API。需要有效的API密钥。```json
{
"env": {
"ZVEC_MCP_EMBEDDING": "openai",
"OPENAI_API_KEY": "sk-..."
}
}

您可以自定义模型和尺寸:```json
{
"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摄入是如何工作的

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

### 记忆是如何工作的

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

______________________________________________________________________

## 数据存储

所有数据都存在于 `ZVEC_MCP_DATA_DIR` (默认值 `~/.zvec-mcp/`):```
~/.zvec-mcp/
├── knowledge/    # zvec collection for RAG chunks
└── memory/       # zvec collection for memories

集合在首次使用时自动创建。要重置所有内容,请删除目录:```bash
rm -rf ~/.zvec-mcp


______________________________________________________________________

## 故障排除

### 服务器未显示为已连接```bash
# 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.安装它:```bash
pip install sentence-transformers


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

### 重置数据库

要重新开始,请删除数据目录:```bash
rm -rf ~/.zvec-mcp

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


构建.mcpb包

要从源代码构建桌面扩展,请执行以下操作:```bash

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

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
zvec MCP 怎么安装?

在客户端按下面的安装命令接入:pip install zvec-mcp。装完在客户端配置里引用同一个包或端点。

zvec MCP 怎么在 Claude 里配置?

它的传输方式是stdio · 本地进程,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

zvec MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

zvec MCP 需要 API Key 吗?

资料标注为无需认证,装好就能连;如果实际调用时报鉴权错误,按官方文档补上凭据。

zvec MCP 支持哪些客户端?

资料标注支持 Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

zvec MCP 能提供哪些能力?

资料显示约 11 个工具;能力标签包括 向量数据库、Python、Claude。具体工具清单以官方文档为准。

zvec MCP 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

zvec MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。