Chroma - 开源嵌入数据库.
使用记忆构建 Python 或 JavaScript LLM 应用的最快方式！

| | 文档 | 主页

Chroma MCP 服务器

模型上下文协议（MCP） 是一种开放协议，旨在实现 LLM 应用程序与外部数据源或工具之间的无缝集成，提供标准化框架，使 LLM 能够轻松获取所需的上下文信息。

该服务器基于 Chroma 提供数据检索功能，支持 AI 模型对生成数据和用户输入创建集合，并通过向量搜索、全文搜索、元数据过滤等方式检索这些数据。

这是一个用于自托管 Chroma 访问权限的 MCP 服务器。如果您正在寻找 Package Search，可以在此处找到其仓库：https://github.com/chroma-core/package-search。

功能

• 灵活的客户端类型

  • 短暂型（内存中）：用于测试和开发
  • 持久型：基于文件存储
  • HTTP 客户端：用于自托管的 Chroma 实例
  • 云客户端：用于 Chroma Cloud 集成（自动连接到 api.trychroma.com）

• 集合管理

  • 创建、修改和删除集合
  • 分页列出所有集合
  • 获取集合信息和统计信息
  • 配置 HNSW 参数以优化向量搜索
  • 在创建集合时选择嵌入函数

• 文档操作

  • 添加带有可选元数据和自定义 ID 的文档
  • 使用语义搜索查询文档
  • 基于元数据和文档内容进行高级过滤
  • 根据 ID 或过滤条件检索文档
  • 全文搜索功能

支持的工具

• 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_add_documents - 添加文档，可选元数据和自定义 ID
• chroma_query_documents - 使用语义搜索结合高级过滤查询文档
• chroma_get_documents - 根据 ID 或过滤条件分页检索文档
• chroma_update_documents - 更新现有文档的内容、元数据或嵌入向量
• chroma_delete_documents - 从集合中删除特定文档

嵌入函数

Chroma MCP 支持多种嵌入函数：default、cohere、openai、jina、voyageai 和 roboflow。

嵌入函数会利用 Chroma 的集合配置，该配置会持久化集合所选的嵌入函数以便后续检索。一旦使用集合配置创建了集合，在未来的查询和插入操作中，将始终使用相同的嵌入函数，无需再次指定。嵌入函数的持久化功能是在 Chroma 1.0.0 版本中引入的，因此如果您使用版本 ≤0.6.3 创建了集合，则不支持此功能。

当使用依赖外部 API 的嵌入函数时，请务必按照正确的格式添加 API 密钥的环境变量，具体请参阅 嵌入函数环境变量。

与 Claude Desktop 的使用方法

1. 若要添加短暂型客户端，请在 claude_desktop_config.json 文件中添加以下内容：

"chroma": {
    "command": "uvx",
    "args": [
        "chroma-mcp"
    ]
}

2. 若要添加持久型客户端，请在 claude_desktop_config.json 文件中添加以下内容：

"chroma": {
    "command": "uvx",
    "args": [
        "chroma-mcp",
        "--client-type",
        "persistent",
        "--data-dir",
        "/full/path/to/your/data/directory"
    ]
}

这将创建一个持久型客户端，并使用指定的数据目录。

3. 若要连接到 Chroma Cloud，请在 claude_desktop_config.json 文件中添加以下内容：

"chroma": {
    "command": "uvx",
    "args": [
        "chroma-mcp",
        "--client-type",
        "cloud",
        "--tenant",
        "your-tenant-id",
        "--database",
        "your-database-name",
        "--api-key",
        "your-api-key"
    ]
}

这将创建一个云客户端，自动通过 SSL 连接到 api.trychroma.com。

注意：在本地设备上直接在参数中添加 API 密钥是安全的，但为了安全起见，您也可以在 args 列表中使用 --dotenv-path 参数指定自定义的环境配置文件路径，例如："args": ["chroma-mcp", "--dotenv-path", "/custom/path/.env"]。

4. 若要连接到您自己云服务商上的 自托管 Chroma 实例，请在 claude_desktop_config.json 文件中添加以下内容：

"chroma": {
    "command": "uvx",
    "args": [
      "chroma-mcp", 
      "--client-type", 
      "http", 
      "--host", 
      "your-host", 
      "--port", 
      "your-port", 
      "--custom-auth-credentials",
      "your-custom-auth-credentials",
      "--ssl",
      "true"
    ]
}

这将创建一个 HTTP 客户端，连接到您的自托管 Chroma 实例。

示例

您可以在 Chroma MCP 文档 中找到参考用法，例如共享知识库以及如何将记忆添加到上下文窗口中。

使用环境变量

您还可以使用环境变量来配置客户端。服务器会自动从位于 --dotenv-path 指定路径下的 .env 文件（默认为工作目录中的 .chroma_env）或系统环境变量中加载变量。命令行参数优先于环境变量。

# 常用变量
export CHROMA_CLIENT_TYPE="http"  # 或 "cloud"、"persistent"、"ephemeral"

# 对于持久化客户端
export CHROMA_DATA_DIR="/完整/路径/到/你的/数据/目录"

# 对于云客户端（Chroma Cloud）
export CHROMA_TENANT="你的租户ID"
export CHROMA_DATABASE="你的数据库名称"
export CHROMA_API_KEY="你的API密钥"

# 对于HTTP客户端（自托管）
export CHROMA_HOST="你的主机"
export CHROMA_PORT="你的端口"
export CHROMA_CUSTOM_AUTH_CREDENTIALS="你的自定义认证凭据"
export CHROMA_SSL="true"

# 可选：指定 .env 文件路径（默认为 .chroma_env）
export CHROMA_DOTENV_PATH="/路径/到/你的/.env" 

嵌入函数环境变量

当使用需要访问 API 密钥的外部嵌入函数时，请遵循命名规范 CHROMA_<>_API_KEY="<key>"。 例如，要设置 Cohere 的 API 密钥，需设置环境变量 CHROMA_COHERE_API_KEY=""。建议将这些变量添加到某个 .env 文件中，并通过 CHROMA_DOTENV_PATH 环境变量或 --dotenv-path 标志来指定该文件的位置，以确保安全存储。

Chroma MCP 快速上手指南

Chroma MCP 是一个基于模型上下文协议（MCP）的服务器，旨在让大语言模型（如 Claude）能够无缝连接 Chroma 向量数据库。通过它，AI 可以创建集合、存储文档、执行语义搜索及元数据过滤，从而为应用赋予长期记忆能力。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows (WSL2 推荐)。
• Python 环境：建议安装 Python 3.9+。
• UV 包管理器：本项目推荐使用 uv 来运行工具（无需手动安装 Python 依赖包）。
  • 安装命令：curl -LsSf https://astral.sh/uv/install.sh | sh (Linux/macOS) 或在 PowerShell 中运行官方安装脚本。
• Claude Desktop：已安装并配置好 Claude 桌面客户端。
• API Keys（可选）：如果您计划使用 OpenAI、Cohere 等外部嵌入模型，需准备好相应的 API Key。

安装步骤

Chroma MCP 无需复杂的源码编译，主要通过 uvx 直接运行。核心配置在于修改 Claude Desktop 的配置文件。

1. 定位配置文件

找到 Claude Desktop 的配置文件 claude_desktop_config.json：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 配置 MCP 服务器

根据您的使用场景（测试、本地持久化、云端或自建），在配置文件的 "mcpServers" 字段下添加以下任一配置块。

方案 A：临时模式（Ephemeral）

适用于快速测试和开发，数据仅保存在内存中，重启即失。

"chroma": {
    "command": "uvx",
    "args": [
        "chroma-mcp"
    ]
}

方案 B：持久化模式（Persistent）

适用于本地开发，将数据保存到指定目录。

"chroma": {
    "command": "uvx",
    "args": [
        "chroma-mcp",
        "--client-type",
        "persistent",
        "--data-dir",
        "/full/path/to/your/data/directory"
    ]
}

请将 /full/path/to/your/data/directory 替换为您本地的实际路径。

方案 C：连接 Chroma Cloud

适用于使用官方云服务。

"chroma": {
    "command": "uvx",
    "args": [
        "chroma-mcp",
        "--client-type",
        "cloud",
        "--tenant",
        "your-tenant-id",
        "--database",
        "your-database-name",
        "--api-key",
        "your-api-key"
    ]
}

方案 D：连接自建 Chroma 实例

适用于连接部署在自己服务器上的 Chroma。

"chroma": {
    "command": "uvx",
    "args": [
      "chroma-mcp", 
      "--client-type", 
      "http", 
      "--host", 
      "your-host", 
      "--port", 
      "your-port", 
      "--custom-auth-credentials",
      "your-custom-auth-credentials",
      "--ssl",
      "true"
    ]
}

安全提示：建议在项目目录下创建 .env 文件存储敏感信息（如 API Key），并在 args 中添加 "--dotenv-path", "/path/to/.env" 参数，避免将密钥硬编码在 JSON 配置中。

基本使用

配置完成后，重启 Claude Desktop。您现在可以在对话中直接使用自然语言操作向量数据库。

支持的常用操作

Chroma MCP 提供了丰富的工具供 AI 调用，包括但不限于：

• chroma_create_collection：创建新的知识库集合。
• chroma_add_documents：向集合中添加文档（支持自动嵌入）。
• chroma_query_documents：执行语义搜索查询。
• chroma_list_collections：查看现有集合列表。

使用示例

场景 1：创建知识库并添加内容 您可以直接在对话框中输入：

"请创建一个名为 'project_docs' 的集合，并将以下关于 Python 异步编程的笔记添加进去：[此处粘贴笔记内容]。"

AI 会自动调用 chroma_create_collection 和 chroma_add_documents 工具完成操作。如果未指定嵌入模型，默认使用内置函数；若需使用 OpenAI 等，请确保已在环境变量中配置 CHROMA_OPENAI_API_KEY。

场景 2：检索信息

"在 'project_docs' 集合中搜索关于 'asyncio' 的相关内容，并总结给我。"

AI 将调用 chroma_query_documents 进行向量检索，结合上下文为您提供精准答案。

场景 3：查看集合状态

"告诉我当前有哪些集合，以及 'project_docs' 里有多少个文档。"

AI 将调用 chroma_list_collections 和 chroma_get_collection_count 返回统计信息。

环境变量配置（进阶）

如果需要全局配置嵌入模型的 API Key，可以在终端导出变量或在 .env 文件中设置：

# 设置 OpenAI API Key (用于嵌入)
export CHROMA_OPENAI_API_KEY="sk-..."

# 指定 .env 文件路径
export CHROMA_DOTENV_PATH="/path/to/your/.env"

支持的嵌入模型包括：default, cohere, openai, jina, voyageai, roboflow。