Chroma MCP 服务器

模型上下文协议 (MCP) 服务器，使用 ChromaDB 提供语义搜索和文档管理功能。该服务器使 LLM 能够利用直观的相似性指标对文档集合执行自然语言查询，使其成为 RAG（检索增强生成）应用的理想选择。

特征

语义搜索：使用最先进的嵌入技术根据含义查找文档
直观的相似性指标：结果包括人性化的相似性分数（0-100％）
文档管理：对文档和集合进行完整的 CRUD 操作
丰富的元数据支持：通过自定义元数据字段附加和搜索
持久存储：使用 SQLite 后端的可靠文档存储
安全性：可配置的访问控制和输入验证
错误处理：全面的错误消息和优雅的故障恢复

要求

Python 3.12 或更高版本
ChromaDB 0.4.22 或更高版本
MCP Python SDK 1.1.2 或更高版本
uv 包管理器（推荐）或 pip

快速入门

# Clone the repository
git clone https://github.com/privetin/mcp-server-chroma.git
cd mcp-server-chroma

# Install with uv (recommended)
uv venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Unix
uv pip install -e .

# Or with pip
python -m venv .venv
.venv\Scripts\activate  # Windows
source .venv/bin/activate  # Unix
pip install -e .

# Run the server
mcp-server-chroma

对于 Claude Desktop 集成，请参阅安装。

建筑学

该服务器建立在：

ChromaDB用于向量存储和搜索
用于服务器实现的MCP Python SDK
SQLite 用于持久存储

数据流

使用 ChromaDB 的默认嵌入模型嵌入文档
嵌入和元数据存储在 ChromaDB 的 SQLite 后端
查询通过相同的嵌入模型进行处理
结果标准化为 0-100% 相似度尺度

成分

收藏品和文件

服务器管理两种主要资源类型：

集合：具有共享嵌入设置的相关文档的容器
文档：带有元数据和自动生成的嵌入的文本内容

工具

收藏管理

list-collections ：列出所有可用的集合
create-collection ：使用可选设置创建新集合
delete-collection ：删除集合及其文档

文档操作

add-document ：添加包含内容和元数据的新文档
get-document ：通过 ID 检索特定文档
update-document ：修改文档内容或元数据
delete-document ：从集合中删除文档
search-documents ：使用规范化相似度分数进行语义搜索

安装

先决条件

Python 3.12+
uv 包管理器（推荐）或 pip

设置

克隆存储库：

git clone https://github.com/privetin/mcp-server-chroma.git
cd mcp-server-chroma

创建并激活虚拟环境：

uv venv
# On Windows:
.venv\Scripts\activate
# On Unix:
source .venv/bin/activate

安装依赖项：

uv pip install -e .

Claude 桌面集成

将服务器添加到您的 Claude Desktop 配置：

Windows （ %APPDATA%/Claude/claude_desktop_config.json ）：

{
  "mcpServers": {
    "chroma": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\mcp-server-chroma",
        "run",
        "mcp-server-chroma"
      ]
    }
  }
}

MacOS （ ~/Library/Application Support/Claude/claude_desktop_config.json ）：

{
  "mcpServers": {
    "chroma": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/mcp-server-chroma",
        "run",
        "mcp-server-chroma"
      ]
    }
  }
}

使用示例

管理收藏

创建集合：

Tool: create-collection
Args: {"name": "research-papers"}

列出集合：

Tool: list-collections
Args: {}

处理文档

添加文档：

Tool: add-document
Args: {
  "collection": "research-papers",
  "content": "Recent advances in transformer architectures have led to significant improvements in natural language processing tasks.",
  "metadata": {
    "title": "Transformer Architectures",
    "year": 2024,
    "category": "ML"
  }
}

获取特定文档：

Tool: get-document
Args: {
  "collection": "research-papers",
  "document_id": "doc_123"
}

更新文档：

Tool: update-document
Args: {
  "collection": "research-papers",
  "document_id": "doc_123",
  "content": "Updated findings on transformer architectures show improvements in both efficiency and accuracy.",
  "metadata": {
    "title": "Transformer Architectures - Updated",
    "year": 2024,
    "category": "ML",
    "status": "updated"
  }
}

搜索文件：

Tool: search-documents
Args: {
  "collection": "research-papers",
  "query": "What are the latest developments in transformers?",
  "n_results": 3
}

理解相似度分数

搜索结果包括 0-100% 的标准化相似度分数：

90-100％ ：内容几乎相同或语义匹配度非常高
70-89％ ：高度相关，语义相似度高
50-69％ ：中度相关，部分语义重叠
30-49% ：有一定关联，但语义联系极小
0-29% ：可能不相关或语义联系非常弱

故障排除

常见问题

数据库连接错误
- 确保数据库路径可写
- 检查是否有其他进程正在使用数据库
- 尝试删除.chroma目录并重新启动
内存问题
- 大型集合可能需要更多 RAM
- 考虑使用较小的批量大小
- 使用--log-level DEBUG监控内存使用情况
搜索性能缓慢
- 大型集合可能需要索引优化
- 考虑使用更少的n_results
- 检查系统资源使用情况

调试模式

以调试模式运行服务器：

mcp-server-chroma --log-level DEBUG

获取帮助

检查ChromaDB 文档
在 GitHub 上打开一个问题
加入 MCP 社区讨论

发展

运行测试

运行测试套件：

pytest -v

覆盖运行：

pytest --cov=chroma tests/

调试

如需调试，请使用 MCP Inspector：

# Install the inspector
npm install -g @modelcontextprotocol/inspector

# Run the server with inspector
mcp-inspector uv --directory /path/to/mcp-server-chroma run mcp-server-chroma

检查员提供：

实时请求/响应监控
工具测试接口
性能指标
错误追踪

错误处理

服务器提供了常见场景的详细错误信息：

集合名称或 ID 无效
文档缺失或格式错误
数据库连接问题
搜索参数无效
身份验证/授权失败

安全注意事项

所有参数的输入验证
可配置的访问控制
安全处理文件路径
防范注入攻击
速率限制支持
安全错误消息

配置

数据库位置

设置自定义数据库路径：

mcp-server-chroma --db-path /path/to/db

默认值：服务器目录中的.chroma

环境变量

CHROMA_DB_PATH ：覆盖数据库位置
CHROMA_LOG_LEVEL ：设置日志详细程度（默认值：INFO）
CHROMA_MAX_CONNECTIONS ：数据库连接池大小（默认值：10）

贡献

分叉存储库
创建功能分支
进行更改
添加新功能测试
提交拉取请求

请阅读我们的贡献指南以了解更多详细信息。

执照

MIT 许可证

特此授予获得此软件和相关文档文件（“软件”）副本的任何人免费许可，以无限制方式处理软件，包括但不限于使用、复制、修改、合并、发布、分发、再授权和/或销售软件副本的权利，并允许向其提供软件的人员这样做，但须遵守以下条件：

Chroma MCP Server