Chroma MCP Server

# 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: ```bash uv venv uv sync --dev --all-extras ``` ## 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` ```json { "mcpServers": { "chroma": { "command": "uv", "args": [ "--directory", "C:/MCP/server/community/chroma", "run", "chroma" ] } } } ``` ### Data Storage The server stores data in: - Windows: `src/chroma/data` - MacOS/Linux: `src/chroma/data` ## Usage 1. Start the server: ```bash uv run chroma ``` 2. Use MCP tools to interact with the server: ```python # 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" } }) ``` ## 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: ```bash npx @modelcontextprotocol/inspector uv --directory C:/MCP/server/community/chroma run chroma ``` 2. Use the inspector's web interface to: - Test CRUD operations - Verify search functionality - Check error handling - Monitor server logs ### Building 1. Update dependencies: ```bash uv compile pyproject.toml ``` 2. Build package: ```bash uv build ``` ## Contributing Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) for details on: - Code style - Testing requirements - Pull request process ## License This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.