Chroma MCP Server

A Model Context Protocol (MCP) server implementation that provides vector database capabilities through Chroma. This server enables semantic document search, metadata filtering, and document management with persistent storage.

Requirements

• Python 3.8+

• Chroma 0.4.0+

• MCP SDK 0.1.0+

Components

Resources

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

• Stores documents with content and metadata

• Persists data in src/chroma/data directory

• Supports semantic similarity search

Tools

The server implements CRUD operations and search functionality:

Document Management

• create_document: Create a new document

  • Required: document_id, content

  • Optional: metadata (key-value pairs)

  • Returns: Success confirmation

  • Error: Already exists, Invalid input

• read_document: Retrieve a document by ID

  • Required: document_id

  • Returns: Document content and metadata

  • Error: Not found

• update_document: Update an existing document

  • Required: document_id, content

  • Optional: metadata

  • Returns: Success confirmation

  • Error: Not found, Invalid input

• delete_document: Remove a document

  • Required: document_id

  • Returns: Success confirmation

  • Error: Not found

• list_documents: List all documents

  • Optional: limit, offset

  • Returns: 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: Ranked list of similar documents with distance scores

  • Error: 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: Data persists in local directory between server restarts

• Error Handling: Comprehensive error handling with clear messages

• Retry Logic: Automatic retries for transient failures

Installation

1. Install dependencies:

Configuration

Claude Desktop

Add the server configuration to your Claude Desktop config:

Windows: C:\Users\<username>\AppData\Roaming\Claude\claude_desktop_config.json

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Data Storage

The server stores data in:

• Windows: src/chroma/data

• MacOS/Linux: src/chroma/data

Usage

1. Start the server:

2. Use MCP tools to interact with the server:

Error Handling

The server provides clear error messages for common scenarios:

• Document already exists [id=X]

• Document not found [id=X]

• Invalid input: Missing document_id or content

• Invalid filter

• Operation failed: [details]

Development

Testing

1. Run the MCP Inspector for interactive testing:

2. Use the inspector's web interface to:

   • Test CRUD operations

   • Verify search functionality

   • Check error handling

   • Monitor server logs

Building

1. Update dependencies:

2. Build package:

Contributing

Contributions are welcome! Please read our Contributing Guidelines for details on:

• Code style

• Testing requirements

• Pull request process

License

This project is licensed under the MIT License - see the LICENSE file for details.