使用说明

ChromaDB MCP 服务器

一个全面的模型上下文协议（MCP）服务器，它将ChromaDB向量数据库操作作为MCP工具暴露出来。该服务器允许AI助手和其他MCP客户端通过标准化接口与ChromaDB数据库进行交互。

特点/特性

藏品管理创建、列出、获取和删除集合
文档操作添加、查询、更新和删除文档
向量相似度搜索使用文本或嵌入查询进行语义搜索
元数据过滤根据文档元数据和内容过滤查询
收藏统计获取有关集合及其内容的信息
异步/等待支持使用asyncio构建，以实现高性能

安装

创建并激活虚拟环境：

# Create virtual environment
python3 -m venv venv

# Activate the virtual environment
source venv/bin/activate

使用 Hatch 安装项目：

# Install in development mode with all dependencies
pip install hatch
hatch env create
hatch run pip install -e .

# Or simply use pip with the project (after installing hatch)
pip install -e ".[dev]"

# Optional: Install additional embedding providers
pip install -e ".[openai]"          # For OpenAI embeddings
pip install -e ".[cohere]"          # For Cohere embeddings (LangChain compatible)
pip install -e ".[instructor]"      # For Instructor embeddings (LangChain compatible)
pip install -e ".[sentence-transformers]"  # For Sentence Transformers
pip install -e ".[huggingface]"     # For HuggingFace models

验证安装：

hatch run chroma-mcp-server --help
# or
python -m app.chroma_mcp_server --help

运行服务器：

# Using Hatch (recommended)
hatch run serve

# Or using Python directly (make sure virtual env is activated)
python -m app.chroma_mcp_server

# Or using the script entry point
chroma-mcp-server

# Run with specific transport (stdio, http, sse)
python -m app.chroma_mcp_server stdio
python -m app.chroma_mcp_server http 127.0.0.1 8000
python -m app.chroma_mcp_server sse 127.0.0.1 8000

确保 ChromaDB 正在运行。您可以本地启动它：

# For local persistent storage
chroma run --path ./chroma_data

# Or for in-memory (will be lost on restart)
chroma run

ChromaDB 连接模式

该服务器支持多种ChromaDB连接模式：

HTTP 模式（默认）

通过HTTP连接到正在运行的ChromaDB服务器
需要 CHROMA_HOST 并且 CHROMA_PORT （默认：localhost:8000）
最适合用于：生产环境、共享数据库、远程服务器

持久模式

使用本地ChromaDB持久化客户端（无需网络）
需要 CHROMA_PERSIST_DIRECTORY 或者默认为 ./chroma_db
最适合：本地开发，单用户场景

记忆模式

使用内存中的ChromaDB（速度最快，重启时数据丢失）
无需配置 - 直接设置即可 CHROMA_MODE=memory
最适合用于：测试、临时数据、快速原型制作

配置优先级和CLI选项

CLI 标志覆盖来自环境变量的设置 .env。
如果提供了CLI选项，则它将优先于任何 .env 价值。

可用的CLI覆盖选项：

# Backend selection
--chroma-mode [http|persistent|memory]

# HTTP mode parameters (when --chroma-mode=http)
--chroma-host <host>
--chroma-port <port>

# Persistent mode parameter (when --chroma-mode=persistent)
--chroma-persist-directory <path>

## Usage Examples

```bash
# HTTP mode (default) - connect to ChromaDB server
hatch run chroma-mcp-server stdio --chroma-mode http --chroma-host localhost --chroma-port 8000

# Persistent mode - local database with persistence
hatch run chroma-mcp-server stdio --chroma-mode persistent --chroma-persist-directory ./my_data

# Memory mode - fast in-memory database
hatch run chroma-mcp-server stdio --chroma-mode memory

# SSE transport with persistent backend and explicit host/port
hatch run chroma-mcp-server sse 0.0.0.0 8091 --chroma-mode persistent --chroma-persist-directory ./chroma_data

# HTTP transport with explicit host/port and HTTP backend
hatch run chroma-mcp-server http 127.0.0.1 8090 --chroma-mode http --chroma-host localhost --chroma-port 8000

# CLI options override .env values
hatch run chroma-mcp-server stdio --chroma-mode http --chroma-host my-chroma-server.com --chroma-port 8080

CHROMA_HOSTChromaDB 主机（默认：localhost）
CHROMA_PORTChromaDB 端口（默认：8000）- 可选，可省略
CHROMA_PERSIST_DIRECTORY持久化存储路径（可选）
CHROMA_MODE连接模式 - http （默认）， persistent或者 memory
DEFAULT_EMBEDDING_PROVIDER默认嵌入提供程序（sentence-transformers、openai、cohere、instructor、huggingface）
DEFAULT_EMBEDDING_MODEL默认嵌入模型名称
OPENAI_API_KEYOpenAI嵌入的OpenAI API密钥
COHERE_API_KEYCohere嵌入的Cohere API密钥

发展

使用Hatch环境

这个项目使用Hatch进行环境管理和开发工作流程：

# Create and enter development environment
hatch shell

# Run tests
hatch run test

# Format code
hatch run format

# Lint code
hatch run lint

# Type check
hatch run type-check

# Run server in development mode
hatch run python -m app.chroma_mcp_server

虚拟环境管理

# Create virtual environment
python -m venv venv

# Activate the virtual environment
source venv/bin/activate

# Deactivate when done
deactivate

项目结构

src/app/ - 主应用程序包
- chroma_mcp_server.py - 主MCP服务器实现
- __init__.py - 包初始化
pyproject.toml - 项目配置和依赖项
example_usage.py - 使用示例和演示
MCP客户端的JSON格式配置文件

可用的MCP工具

藏品管理

`list_collections()`

列出数据库中的所有集合及其元数据。

回报集合信息的JSON数组

`create_collection(name, metadata, embedding_config)`

创建一个新的集合。

参数：

name (字符串): 集合名称
metadata （字典，可选）：集合元数据
embedding_config （字典，可选）：嵌入函数配置：
- provider 字符串类型："sentence-transformers"、"openai"、"cohere"、"instructor" 或 "huggingface"
- model (字符串): 模型名称（例如，“all-MiniLM-L6-v2”，“text-embedding-ada-002”，“embed-english-v3.0”）
- api_key (str, optional): 提供商服务的API密钥

`get_collection(name)`

获取特定集合的信息。

参数：

name (str): 集合名称

退货收藏信息，包括文档数量

`delete_collection(name)`

删除一个集合及其所有文档。

参数：

name (字符串): 集合名称

文档操作

`add_documents(collection_name, documents)`

将文档添加到集合中。

参数：

collection_name (字符串): 目标集合名称
documents (数组): 包含文档对象的数组，其中：
- id (字符串): 唯一文档标识符
- content (字符串): 文档文本内容
- metadata （字典，可选）：文档元数据
- embedding （数组，可选）：预计算的嵌入向量

`query_collection(query)`

在集合上执行相似性搜索。

参数：

query (对象)：使用以下配置查询：
- collection_name (字符串): 目标集合
- query_texts （数组，可选）：用于语义搜索的文本查询
- query_embeddings （数组，可选）：用于直接相似度搜索的嵌入向量
- n_results (int, 默认值: 10)：要返回的结果数量
- where (字典，可选)：元数据过滤器
- where_document （字典，可选）：文档内容过滤器

回报查询结果包含文档、元数据和相似度得分

`update_document(update)`

更新现有文档。

参数：

update (对象)：使用以下内容更新配置：
- collection_name (字符串): 目标集合
- document_id (字符串)：要更新的文档
- content (字符串，可选)：新内容
- metadata （字典，可选）：新的元数据
- embedding （数组，可选）：新的嵌入

`delete_documents(collection_name, document_ids)`

从集合中删除文档。

参数：

collection_name (str): 目标集合
document_ids (数组)：要删除的文档ID数组

`get_document(collection_name, document_id)`

检索特定文档。

参数：

collection_name (字符串): 目标集合
document_id (字符串): 要检索的文档ID

实用工具

`collection_stats(collection_name)`

获取集合的统计数据。

参数:

collection_name (字符串): 目标集合

`peek_collection(collection_name, limit)`

查看集合中的前几个文档。

参数:

collection_name (字符串): 目标集合
limit (int, 默认值: 10)：要返回的最大文档数

使用示例

与LangChain兼容的嵌入示例

# Create collection with Cohere embeddings (popular in LangChain)
await create_collection("docs", embedding_config={
    "provider": "cohere",
    "model": "embed-english-v3.0",
    "api_key": "your-cohere-key"
})

# Create collection with Instructor embeddings (optimized for instructions)
await create_collection("instructions", embedding_config={
    "provider": "instructor", 
    "model": "hkunlp/instructor-xl"
})

# Create collection with OpenAI embeddings (standard in LangChain)
await create_collection("embeddings", embedding_config={
    "provider": "openai",
    "model": "text-embedding-ada-002"
})

# Environment-based configuration (great for LangChain integration)
import os
os.environ["DEFAULT_EMBEDDING_PROVIDER"] = "cohere"
os.environ["COHERE_API_KEY"] = "your-key"
os.environ["DEFAULT_EMBEDDING_MODEL"] = "embed-english-v3.0"

添加和查询文档

# Add documents
documents = [
    {
        "id": "doc1",
        "content": "This is a sample document about AI",
        "metadata": {"category": "tech", "year": 2024}
    },
    {
        "id": "doc2",
        "content": "Another document about machine learning",
        "metadata": {"category": "tech", "year": 2024}
    }
]
await add_documents("my_documents", documents)

# Query by text
query = {
    "collection_name": "my_documents",
    "query_texts": ["artificial intelligence"],
    "n_results": 5
}
results = await query_collection(query)

# Query with metadata filters
query = {
    "collection_name": "my_documents",
    "query_texts": ["technology"],
    "where": {"category": "tech"},
    "n_results": 10
}
results = await query_collection(query)

文档管理

# Update a document
await update_document({
    "collection_name": "my_documents",
    "document_id": "doc1",
    "content": "Updated content about AI and machine learning",
    "metadata": {"category": "tech", "year": 2024, "updated": True}
})

# Get a specific document
doc = await get_document("my_documents", "doc1")

# Delete documents
await delete_documents("my_documents", ["doc1", "doc2"])

运行服务器

启动MCP服务器：

python -m app.chroma_mcp_server

服务器将启动并提供MCP工具，这些工具可供兼容的MCP客户端使用。

运输方式

该服务器支持多种传输协议，以满足不同的使用场景：

STDIO 传输（默认）

最适合用于本地开发，与Claude Desktop集成
用法: python -m app.chroma_mcp_server stdio
特性；特点通过标准输入/输出进行直接通信

HTTP传输

最适合于网络可访问性，支持多个并发客户端
使用方法： python -m app.chroma_mcp_server http 127.0.0.1 8000
访问可获取于 http://127.0.0.1:8000/mcp

服务器发送事件（SSE Transport）

最适合于实时流媒体，网页集成
用法: python -m app.chroma_mcp_server sse 127.0.0.1 8000
注传统传输方式，对于新项目建议使用HTTP

MCP 客户端配置

Claude 桌面配置

要使用此服务器与Claude Desktop或其他支持stdio协议的MCP客户端，请将以下配置添加到您的MCP客户端配置文件中：

基本配置 (claude-desktop-config.json)：

{
  "mcpServers": {
    "chroma-db": {
      "command": "python",
      "args": ["-m", "app.chroma_mcp_server", "stdio"],
      "env": {
        "CHROMA_HOST": "localhost",
        "CHROMA_PORT": "8000"
      }
    }
  }
}

SSE 配置 用于网络访问：

{
  "mcpServers": {
    "chroma-sse": {
      "command": "python",
      "args": ["-m", "app.chroma_mcp_server", "sse", "127.0.0.1", "8091", "--chroma-mode", "persistent", "--chroma-persist-directory", "./chroma_data"],
      "cwd": "/home/zoomrec/projects/chroma-mcp-server",
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

配置参数

命令要运行的命令（通常 python）
**参数（或命令行参数）**命令行参数（服务器脚本的路径）
**当前工作目录（Current Working Directory）**工作目录（可选，对相对路径很有用）
**环境（env通常作为environment的缩写）**ChromaDB 连接的环境变量：
- CHROMA_HOSTChromaDB服务器主机名
- CHROMA_PORTChromaDB服务器端口
- CHROMA_PERSIST_DIRECTORY本地持久化存储路径
- LOG_LEVEL日志级别（DEBUG、INFO、WARNING、ERROR）

与LangChain的集成

这个MCP服务器旨在与LangChain应用程序无缝协作。所选的嵌入提供程序是特意为了匹配LangChain中常用的嵌入方式而设计的：

支持LangChain嵌入

OpenAI（开放人工智能研究所）： text-embedding-ada-002 - 在LangChain中最受欢迎
Cohere（科赫尔，此处为音译，实际品牌名可能根据官方翻译有所不同）： embed-english-v3.0 - 高性能替代方案
教练: hkunlp/instructor-xl - 指令调优的嵌入表示
句子变换器（或句向量模型）: all-MiniLM-L6-v2 本地化，无需API
**HuggingFace（注：这是一个专有名词，通常不进行翻译，直接保留原名，指的是一家专注于自然语言处理技术的公司或平台）**来自中心的任何模型

LangChain 集成示例

# In your LangChain application
from langchain.vectorstores import Chroma
from langchain.embeddings import OpenAIEmbeddings, CohereEmbeddings

# Use with LangChain's Chroma wrapper
embeddings = OpenAIEmbeddings(
    model="text-embedding-ada-002",
    openai_api_key="your-key"
)

# Create Chroma collection via MCP server first
# Then use it in LangChain
vectorstore = Chroma(
    collection_name="my_docs",
    embedding_function=embeddings,
    client=your_chroma_client
)

与AI助手的集成

这台服务器旨在与支持模型上下文协议的人工智能助手协同工作。一旦运行起来，助手可以：

自动发现可用工具
使用工具与ChromaDB进行交互
执行向量相似性搜索
管理集合和文档
构建RAG（检索增强生成）应用

错误处理

该服务器包含全面的错误处理机制，并将针对以下情况返回描述性的错误信息：

与ChromaDB的连接问题
无效的集合或文档ID
查询参数错误
网络超时

性能考量

使用 async/await 进行非阻塞操作
支持本地持久化和远程ChromaDB实例
可配置的查询结果限制
高效的文档管理批量操作

故障排除

常见问题

连接被拒绝确保ChromaDB正在指定的主机/端口上运行
未找到集合验证集合名称是否正确
未找到文档检查集合中是否存在文档ID
导入错误确保所有依赖项都已从 pyproject.toml 中安装

记录日志

服务器默认以INFO级别将日志输出到标准输出（stdout）。您可以通过修改服务器文件中的日志配置来调整日志记录。

许可证

这个项目是开源的，并遵循MIT许可证。