Chroma

🚀 Chroma MCP Server

A Model Context Protocol (MCP) server implemented with Chroma, offering vector database capabilities. This server supports semantic document search, metadata filtering, and document management, along with persistent storage.

🚀 Quick Start

Prerequisites

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

Components

Resources

The server provides document storage and retrieval capabilities through Chroma's vector database:

• Store documents with content and metadata.
• Persistently store data in the src/chroma/data directory.
• Support semantic similarity search.

Tools

The server implements CRUD operations and search functions:

Document Management

• create_document: Create a new document

  • Required: document_id, content
  • Optional: metadata (key - value pairs)
  • Returns: Confirmation of success
  • Errors: Already exists, invalid input

• read_document: Retrieve a document by ID

  • Required: document_id
  • Returns: Document content and metadata
  • Errors: Not found

• update_document: Update an existing document

  • Required: document_id, content
  • Optional: metadata
  • Returns: Confirmation of success
  • Errors: Not found, invalid input

• delete_document: Delete a document

  • Required: document_id
  • Returns: Confirmation of success
  • Errors: Not found

• list_documents: List all documents

  • Optional: limit, offset
  • Returns: A list of documents with content and metadata

Search Operations

• search_similar: Find semantically similar documents
  • Required: query
  • Optional: num_results, metadata_filter, content_filter
  • Returns: A ranked list of similar documents with distance scores
  • Errors: Invalid filter

✨ Features

• Semantic Search: Find documents based on meaning, using Chroma's embeddings.
• Metadata Filtering: Filter search results by metadata fields.
• Content Filtering: Additional filtering based on document content.
• Persistent Storage: Retain data across server restarts in a local directory.
• Error Handling: Comprehensive error handling with clear messages.
• Retry Logic: Automatic retry for transient failures.

📦 Installation

1. Install dependencies:

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

📚 Documentation

Configuration

Claude Desktop

Add the server configuration to your Claude Desktop configuration:

Windows: C:\Users\<username>\AppData\Local\Claude Labs\Claude 2\config.json

Add the following to the end of the file:

{
  "mcp-server": {
    "enabled": true,
    "host": "0.0.0.0",
    "port": 5000
  }
}

Windows System Service Configuration

1. Create a new file mcp-service.json with the following content:

{
  "name": "MCP Server",
  "description": "Chroma MCP Server",
  "start_command": "uvicorn mcp_server.main:app --host 0.0.0.0 --port 5000",
  "working_directory": "%USERPROFILE%",
  "autostart": true,
  "display": false
}

2. Save the file in the C:\ProgramData\uvx directory.

Usage

1. Start the server:

python -m mcp_server.main --host 0.0.0.0 --port 5000

Error Handling

• Common Errors: Check if the port is occupied or the configuration is correct.

Development and Testing

1. Clone the repository:

git clone https://github.com/your-repository.git
cd mcp_server
pip install -r requirements.txt

2. Start the server for development:

uvicorn mcp_server.main:app --reload

Contribution Guidelines

1. Fork the repository.
2. Create a feature branch.
3. Commit your changes.
4. Create a Pull Request.

📄 License

This project is licensed under the terms of the LICENSE file.