chroma-mcp
chroma-core/chroma-mcp加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
微信扫码咨询客服
POMOAI — 让开源 AI 即刻运行
加载项目详情…
本应用为开源项目，仅供学习研究，请遵守其开源协议。
图1：Chroma 官方 Logo —— 一只简约的蝴蝶图案，象征向量嵌入在语义空间中"破茧"的能力
想象你正在和一个大模型对话，想让它回答一份内部文档中的某个细节——然而这份文档从未出现在模型的训练数据里。大多数人的解决方案是"把文档内容粘贴到 prompt 里"，但这对于大型知识库来说是不可行的：token 限制、成本、延迟都是拦路虎。
chroma-core/chroma-mcp 正是为解决这个问题而生：它是一个基于 Model Context Protocol（MCP）的服务端，通过 Chroma 向量数据库为 AI 模型提供实时、精准的私有数据检索能力。你可以让 Claude 通过自然语言查询公司的内部知识库、论文库、代码库，而不必把这些数据硬塞进每次请求的上下文里。
Chroma 诞生于 2023 年的大模型应用热潮，定位是"开源的嵌入式向量数据库"（Embedding Database）。它的核心价值在于：开发者只需要上传文档并指定一个嵌入函数（Embedding Function），Chroma 自动将文本切分、向量化并存入向量数据库；查询时只需传入查询文本，系统返回语义最相关的 Top-K 条记录——这正是 RAG（检索增强生成）架构的核心环节。
而 MCP（Model Context Protocol） 是由 Anthropic 在 2024 年初推动的开放协议，旨在标准化 AI 应用与外部数据源/工具之间的连接方式。在 MCP 出现之前，每个 AI 应用（如 Claude Desktop、Cursor）若想接入 Chroma，需要各自编写独立的集成代码；有了 MCP，同一个 Chroma MCP Server 可以被任何兼容 MCP 的客户端即插即用。chroma-mcp 正是这两个趋势的交汇点：它让 Chroma 数据库以一种通用、标准的方式融入任何 MCP 生态的 AI 应用。
项目使用 Python 3.10+ 开发，核心依赖极为精简：
chromadb (≥1.0.16)：Chroma 向量数据库 Python 客户端，提供 EphemeralClient、PersistentClient、HttpClient 等多种接入方式mcp[cli] (1.6.0)：Anthropic 的 MCP Python SDK，提供了 FastMCP 框架来声明式地注册工具openai/cohere/jina/voyageai/roboflow：多个可选的嵌入函数后端，覆盖主流商业 API 和开源方案python-dotenv：配置管理，支持从 .env 文件加载环境变量整个项目只包含两个核心 Python 文件，代码量小但职责清晰：
src/chroma_mcp/server.py（约 26KB）：MCP 服务端主文件，包含所有工具注册、参数解析、客户端工厂src/chroma_mcp/__init__.py：包入口，暴露 main() 函数作为命令行入口server.py 通过命令行参数 --client-type 支持四种 Chroma 客户端模式，这是本项目最核心的设计亮点：
| 模式 | 说明 | 适用场景 |
|---|---|---|
ephemeral | 内存临时数据库，随进程消失 | 本地开发、快速测试 |
persistent | 本地 SQLite 文件持久化存储 | 个人项目、小规模私有部署 |
http | 连接远程自托管 Chroma 实例 | 生产环境、私有云部署 |
cloud | 连接 Chroma Cloud（api.trychroma.com） | 即开即用、SaaS 模式 |
每种模式都通过标准 MCP 工具暴露完整的 CRUD 操作，AI 应用无需感知底层存储差异。
chroma-mcp 暴露了 11 个 MCP 工具，覆盖了向量数据库从创建到查询的完整操作链：
集合管理（Collection）：
chroma_list_collections — 分页列举所有集合chroma_create_collection — 创建集合，支持指定嵌入函数和 HNSW 参数chroma_peek_collection — 预览集合中的样本文档chroma_get_collection_info — 获取集合统计信息chroma_get_collection_count — 获取文档数量chroma_modify_collection — 修改集合名称或元数据chroma_delete_collection — 删除集合chroma_fork_collection — 复制集合文档操作（Document）：
chroma_add_documents — 批量添加文档（带元数据和自定义 ID）chroma_query_documents — 向量语义检索，支持元数据过滤chroma_get_documents — 按 ID 或过滤条件精确获取文档chroma_update_documents — 更新已有文档内容或元数据chroma_delete_documents — 按 ID 删除文档创建集合时可指定嵌入函数，default 使用 Chroma 内置的 sentence-transformers 模型，完全本地运行；openai、cohere、jina、voyageai 则调用对应商业 API，获得更高质量的语义向量。嵌入函数配置会随集合一起持久化，之后的查询和插入无需重复指定。
chroma_query_documents 是最核心的工具，支持：
where 参数支持类似 SQL 的过滤条件（如 {"source": "pdf", "year": 2024}）# 无需任何配置，直接运行（使用内存临时数据库）
uvx chroma-mcp
然后在 Claude Desktop 的 claude_desktop_config.json 中添加配置：
"chroma": {
"command": "uvx",
"args": ["chroma-mcp"]
}
对于 Claude Desktop 用户来说，整个接入过程不超过 5 分钟。
uvx chroma-mcp --client-type persistent --data-dir /path/to/data
通过 Docker 一键部署：
FROM python:3.10-slim
WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends gcc
COPY . /app
RUN pip install --upgrade pip && pip install .
EXPOSE 8080
CMD ["chroma-mcp"]
构建并运行：
docker build -t chroma-mcp .
docker run -p 8080:8080 chroma-mcp --client-type http --host your-chroma-host --port 8000
通过 Smithery（一个 MCP 工具市场）也可以一键部署到各种环境。
如果选择非默认嵌入函数（openai/cohere 等），向量生成依赖商业 API，有两个现实问题：一是成本，每个文档片段调用一次 API，文档量大时费用不可忽视；二是网络延迟，API 调用引入额外延迟，影响实时交互体验。本地 default 嵌入函数使用 sentence-transformers 模型，质量和速度均不如 GPT-4o 等商业服务。
Chroma 的元数据过滤基于等值匹配，不支持复杂的范围查询（如 year > 2020 AND year < 2025 的组合条件语法较为繁琐）。对于结构化数据查询，直接使用 PostgreSQL 可能更合适。
HNSW（Hierarchical Navigable Small World）是一种近似最近邻算法，不是精确搜索。在追求极致的精确匹配场景下（如法律条文检索），需要评估召回率是否可以接受。
chroma-mcp 目前的 GitHub Stars 为 562，虽然绝对数量不大，但它是 MCP 生态中向量数据库集成的最成熟方案，也是 Chroma 官方唯一维护的 MCP Server。
从行业趋势看，MCP 协议正在快速成为 AI 应用连接外部工具和数据的事实标准。Anthropic 之外的厂商（如 Sourcegraph Cody、Block、Replit）也在陆续支持 MCP。在这一生态中，向量数据库是 RAG 架构的核心组件——chroma-mcp 填补了"AI 应用如何便捷接入向量数据库"这一关键空白。
从 Chroma 项目整体来看，GitHub 主仓库拥有约 2.3 万星，是开源向量数据库中用户基数最大的项目之一。chroma-mcp 作为其 MCP 扩展，可以触达所有 MCP 客户端生态的用户，是 Chroma 从"Python 库"走向"跨平台服务"的关键一步。
项目信息：chroma-core/chroma-mcp | ⭐ 562 | Python | Apache-2.0 | v0.2.6（2025-08-14）