使用说明

项目简介

Chroma MCP Server 是一个基于 Model Context Protocol (MCP) 构建的后端服务器，它利用 Chroma 向量数据库，为大型语言模型 (LLM) 客户端提供文档存储、检索和语义搜索能力。该服务器允许 LLM 应用通过标准化的 MCP 协议访问和管理文档资源，进行相似性搜索，并根据元数据进行过滤。它旨在简化 LLM 应用与外部数据源的集成，提供可扩展和安全的上下文服务。

主要功能点

语义搜索：基于文档内容的语义相似性进行搜索，找到相关性高的文档。
文档管理：提供文档的创建、读取、更新、删除和列表查看 (CRUD) 操作。
元数据过滤：支持根据文档的元数据进行精确或条件过滤，提高搜索准确性。
内容过滤：允许基于文档内容关键词进行过滤。
持久化存储：使用本地目录持久化存储文档数据，重启服务器数据不丢失。
错误处理：提供清晰的错误消息，方便问题排查。
重试机制：针对瞬时错误进行自动重试，增强系统稳定性。

安装步骤

安装依赖：打开终端，导航到仓库根目录（包含 'README.md' 的目录），运行以下命令安装项目依赖：
```
uv venv
uv sync --dev --all-extras
```
这将使用 uv (一个更快的 pip 和 venv 替代品) 创建虚拟环境并安装所有必要的 Python 包。

服务器配置

要将 Chroma MCP Server 配置到 MCP 客户端（例如 Claude Desktop），您需要编辑客户端的配置文件。以 Claude Desktop 为例，配置文件路径如下：

Windows: 'C:\Users<username>\AppData\Roaming\Claude\claude_desktop_config.json'
MacOS: '~/Library/Application Support/Claude/claude_desktop_config.json'

在配置文件中，找到 '"mcpServers"' 部分，并添加 Chroma MCP Server 的配置信息。以下是一个示例配置，您可以直接复制粘贴到您的配置文件中：

{
  "mcpServers": {
    "chroma": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/MCP/server/community/chroma",
        "run",
        "chroma"
      ]
    }
  }
}

配置参数说明：

'"chroma"': 服务器名称，您可以自定义，用于在 MCP 客户端中标识该服务器。
'"command": "uv"': 启动服务器的命令，这里使用 'uv run' 来运行 Python 脚本。
'"args"': 传递给 'uv run' 命令的参数列表。
- '"--directory"': 指定服务器代码所在的目录，请务必替换为您的 Chroma MCP Server 仓库的实际路径。例如，如果您的仓库放在 'C:/MCP/server/community/chroma'，则使用 '"C:/MCP/server/community/chroma"'。
- '"run"': 'uv' 命令的子命令，用于运行 Python 脚本。
- '"chroma"': 指定要运行的 Python 脚本的入口点，对应 'src/chroma/init.py' 中定义的 'main' 函数。

重要提示：

请将 '"C:/MCP/server/community/chroma"' 替换为您本地 Chroma MCP Server 仓库的绝对路径。
确保您的 MCP 客户端能够访问到您指定的仓库路径。

基本使用方法

启动服务器：打开终端，导航到仓库根目录，运行以下命令启动 Chroma MCP Server：
```
uv run chroma
```
服务器成功启动后，您应该能在终端看到日志输出，例如 "Retrieved existing collection 'documents'" 或 "Created new collection 'documents'"，以及 "Embedding function initialized successfully" 等信息。
使用 MCP 客户端与服务器交互：配置完成后，您可以使用 MCP 客户端（如 Claude Desktop）连接到 Chroma MCP Server。客户端将通过 MCP 协议与服务器通信，调用服务器提供的工具，例如：
- 创建文档：调用 'create_document' 工具，并提供 'document_id'、'content' 和可选的 'metadata' 参数。
- 搜索相似文档：调用 'search_similar' 工具，并提供 'query'（搜索关键词）以及其他可选的过滤参数。
- 其他文档操作：使用 'read_document'、'update_document'、'delete_document' 和 'list_documents' 工具进行相应的文档管理操作。
具体的工具调用方法取决于您使用的 MCP 客户端。您可以参考客户端的文档或界面操作指南来使用这些工具。例如，在 MCP Inspector 中，您可以直接输入 JSON 格式的请求来调用工具并查看返回结果。

数据存储位置： Chroma MCP Server 默认将数据存储在仓库目录下的 'src/chroma/data' 目录中。

Windows: 'src/chroma/data'
MacOS/Linux: 'src/chroma/data'

关键词