Chroma MCP Server

Chroma MCP 服务

一个 Model Context Protocol（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 a document
create_document({
    "document_id": "ml_paper1",
    "content": "Convolutional neural networks improve image recognition accuracy.",
    "metadata": {
        "year": 2020,
        "field": "computer vision",
        "complexity": "advanced"
    }
})

# Search similar documents
search_similar({
    "query": "machine learning models",
    "num_results": 2,
    "metadata_filter": {
        "year": 2020,
        "field": "computer vision"
    }
})

错误处理

此服务会针对常见情况提供清晰的错误提示：

• Document already exists [id=X]
• Document not found [id=X]
• Invalid input: Missing document_id or 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

贡献

欢迎贡献！请阅读我们的贡献指南，了解以下详情：

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

许可证

本项目采用 MIT 许可证授权，详情请参阅 LICENSE 文件。