Skip to main content
Glama
enesjakozh
privetin

Chroma MCP Server

by privetin
OverviewSchemaRelated ServersDiscussionsAdmin
Python
Remote

Chroma MCP 服务器

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

微胶囊钙 Python执照 测试 代码样式：黑色

特征

  • 语义搜索：使用最先进的嵌入技术根据含义查找文档

  • 直观的相似性指标：结果包括人性化的相似性分数（0-100％）

  • 文档管理：对文档和集合进行完整的 CRUD 操作

  • 丰富的元数据支持：通过自定义元数据字段附加和搜索

  • 持久存储：使用 SQLite 后端的可靠文档存储

  • 安全性：可配置的访问控制和输入验证

  • 错误处理：全面的错误消息和优雅的故障恢复

Related MCP server: MCP Server for OpenSearch

要求

  • 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 集成，请参阅安装。

建筑学

该服务器建立在：

数据流

  1. 使用 ChromaDB 的默认嵌入模型嵌入文档

  2. 嵌入和元数据存储在 ChromaDB 的 SQLite 后端

  3. 查询通过相同的嵌入模型进行处理

  4. 结果标准化为 0-100% 相似度尺度

成分

收藏品和文件

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

  • 集合：具有共享嵌入设置的相关文档的容器

  • 文档：带有元数据和自动生成的嵌入的文本内容

工具

收藏管理

  • list-collections ：列出所有可用的集合

  • create-collection ：使用可选设置创建新集合

  • delete-collection ：删除集合及其文档

文档操作

  • add-document ：添加包含内容和元数据的新文档

  • get-document ：通过 ID 检索特定文档

  • update-document ：修改文档内容或元数据

  • delete-document ：从集合中删除文档

  • search-documents ：使用规范化相似度分数进行语义搜索

安装

先决条件

  • Python 3.12+

  • uv 包管理器（推荐）或 pip

设置

  1. 克隆存储库：

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

  1. 创建并激活虚拟环境：

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

  1. 安装依赖项：

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% ：可能不相关或语义联系非常弱

故障排除

常见问题

  1. 数据库连接错误

    • 确保数据库路径可写

    • 检查是否有其他进程正在使用数据库

    • 尝试删除.chroma目录并重新启动

  2. 内存问题

    • 大型集合可能需要更多 RAM

    • 考虑使用较小的批量大小

    • 使用--log-level DEBUG监控内存使用情况

  3. 搜索性能缓慢

    • 大型集合可能需要索引优化

    • 考虑使用更少的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）

贡献

  1. 分叉存储库

  2. 创建功能分支

  3. 进行更改

  4. 添加新功能测试

  5. 提交拉取请求

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

执照

MIT 许可证

版权所有 (c) 2024 privetin

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

上述版权声明和本许可声明均应包含在软件的所有副本或实质性部分中。

本软件按“原样”提供，不附带任何形式的明示或暗示保证，包括但不限于适销性、适用于特定用途和非侵权性的保证。在任何情况下，作者或版权所有者均不对因本软件或使用或以其他方式处理本软件而引起的或与之相关的任何索赔、损害或其他责任承担责任，无论是合同、侵权或其他诉讼。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches