Chroma MCP 服务器

一个模型上下文协议 (MCP) 服务器的实现，通过 Chroma 提供向量数据库功能。该服务器支持语义文档搜索、元数据过滤和文档管理，并具有持久存储能力。

要求

• Python 3.8+
• Chroma 0.4.0+
• MCP SDK 0.1.0+

组件

资源

该服务器通过 Chroma 的向量数据库提供文档存储和检索：

• 存储包含内容和元数据的文档
• 将数据持久化存储在 src/chroma/data 目录中
• 支持语义相似度搜索

工具

该服务器实现了 CRUD 操作和搜索功能：

文档管理

• create_document: 创建一个新文档

  • 必需: document_id, content
  • 可选: metadata (键值对)
  • 返回: 成功确认
  • 错误: 已存在, 无效输入

• read_document: 通过 ID 检索文档

  • 必需: document_id
  • 返回: 文档内容和元数据
  • 错误: 未找到

• update_document: 更新现有文档

  • 必需: document_id, content
  • 可选: metadata
  • 返回: 成功确认
  • 错误: 未找到, 无效输入

• delete_document: 删除文档

  • 必需: document_id
  • 返回: 成功确认
  • 错误: 未找到

• list_documents: 列出所有文档

  • 可选: limit, offset
  • 返回: 包含内容和元数据的文档列表

搜索操作

• search_similar: 查找语义上相似的文档
  • 必需: query
  • 可选: num_results, metadata_filter, content_filter
  • 返回: 具有距离分数的相似文档的排名列表
  • 错误: 无效的过滤器

特性

• 语义搜索: 使用 Chroma 的嵌入根据含义查找文档
• 元数据过滤: 按元数据字段过滤搜索结果
• 内容过滤: 基于文档内容的附加过滤
• 持久存储: 数据在服务器重启之间持久保存在本地目录中
• 错误处理: 具有清晰消息的全面错误处理
• 重试逻辑: 自动重试瞬时故障

安装

1. 安装依赖:

uv venv
uv sync --dev --all-extras

配置

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": {
      "command": "uv",
      "args": [
        "--directory",
        "C:/MCP/server/community/chroma",
        "run",
        "chroma"
      ]
    }
  }
}

数据存储

服务器将数据存储在：

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

用法

1. 启动服务器:

uv run chroma

2. 使用 MCP 工具与服务器交互:

# 创建一个文档
create_document({
    "document_id": "ml_paper1",
    "content": "卷积神经网络提高了图像识别的准确性。",
    "metadata": {
        "year": 2020,
        "field": "computer vision",
        "complexity": "advanced"
    }
})

# 搜索相似的文档
search_similar({
    "query": "机器学习模型",
    "num_results": 2,
    "metadata_filter": {
        "year": 2020,
        "field": "computer vision"
    }
})

错误处理

服务器为常见场景提供清晰的错误消息：

• Document already exists [id=X] (文档已存在 [id=X])
• Document not found [id=X] (未找到文档 [id=X])
• Invalid input: Missing document_id or content (无效输入：缺少 document_id 或 content)
• Invalid filter (无效的过滤器)
• Operation failed: [details] (操作失败：[详细信息])

开发

测试

1. 运行 MCP Inspector 进行交互式测试：

npx @modelcontextprotocol/inspector uv --directory C:/MCP/server/community/chroma run chroma

2. 使用 inspector 的 Web 界面来：
   • 测试 CRUD 操作
   • 验证搜索功能
   • 检查错误处理
   • 监控服务器日志

构建

1. 更新依赖:

uv compile pyproject.toml

2. 构建包:

uv build

贡献

欢迎贡献！请阅读我们的 Contributing Guidelines 以了解有关以下内容的详细信息：

• 代码风格
• 测试要求
• Pull request 流程

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参见 LICENSE 文件。