Metadata-Version: 2.4
Name: chroma-mcp-server
Version: 0.1.5
Summary: Chroma MCP Server - Vector Database Integration for LLM Applications
Project-URL: Homepage, https://github.com/djm81/chroma_mcp_server
Project-URL: Repository, https://github.com/djm81/chroma_mcp_server.git
Project-URL: Documentation, https://github.com/djm81/chroma_mcp_server#readme
Author-email: Nold Coaching & Consulting <info@noldcoaching.de>
License-Expression: MIT
License-File: LICENSE.md
Keywords: chroma,embeddings,llm,mcp,vector-database
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: chromadb>=0.6.3
Requires-Dist: fastapi>=0.115.11
Requires-Dist: fastmcp>=0.4.1
Requires-Dist: numpy>=2.2.0
Requires-Dist: pydantic>=2.10.6
Requires-Dist: python-dotenv>=1.1.0
Requires-Dist: uvicorn>=0.34.0
Provides-Extra: dev
Requires-Dist: black>=25.1.0; extra == 'dev'
Requires-Dist: isort>=6.0.0; extra == 'dev'
Requires-Dist: mypy>=1.15.0; extra == 'dev'
Requires-Dist: pylint>=3.3.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.26.0; extra == 'dev'
Requires-Dist: pytest-cov>=6.0.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.14.0; extra == 'dev'
Requires-Dist: pytest-xdist[psutil]>=3.5.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.0; extra == 'dev'
Provides-Extra: full
Requires-Dist: httpx>=0.28.0; extra == 'full'
Requires-Dist: onnxruntime>=1.21.0; extra == 'full'
Requires-Dist: sentence-transformers>=4.0.1; extra == 'full'
Description-Content-Type: text/markdown

# Chroma MCP Server

[![CI](https://github.com/djm81/chroma_mcp_server/actions/workflows/tests.yml/badge.svg)](https://github.com/djm81/chroma_mcp_server/actions/workflows/tests.yml)
[![codecov](https://codecov.io/gh/djm81/chroma_mcp_server/branch/main/graph/badge.svg)](https://codecov.io/gh/djm81/chroma_mcp_server)
![PyPI - Version](https://img.shields.io/pypi/v/chroma-mcp-server?color=blue)

A Model Context Protocol (MCP) server integration for [Chroma](https://www.trychroma.com/), the open-source embedding database.

## Overview

The Chroma MCP Server allows you to connect AI applications with Chroma through the Model Context Protocol. This enables AI models to:

- Store and retrieve embeddings
- Perform semantic search on vector data
- Manage collections of embeddings
- Support RAG (Retrieval Augmented Generation) workflows

## Installation

Choose your preferred installation method:

### Standard Installation

```bash
# Using pip
pip install chroma-mcp-server

# Using UVX (recommended for Cursor)
uv pip install chroma-mcp-server
```

### Full Installation (with embedding models)

```bash
# Using pip
pip install chroma-mcp-server[full]

# Using UVX
uv pip install "chroma-mcp-server[full]"
```

### Development Installation

This project uses [Hatch](https://hatch.pypa.io/) for development and package management. See the **Development** section below for setup instructions.

## Usage

### Starting the server

```bash
# Using the command-line executable
chroma-mcp-server

# Or using the Python module
python -m chroma_mcp.server
```

Or use the provided scripts during development:

```bash
# For development environment
./scripts/develop.sh

# To build the package
./scripts/build.sh

# To publish to PyPI
./scripts/publish.sh
```

### Configuration

The server can be configured with command-line options or environment variables:

#### Command-line Options

```bash
chroma-mcp-server --client-type persistent --data-dir ./my_data
```

#### Environment Variables

```bash
export CHROMA_CLIENT_TYPE=persistent
export CHROMA_DATA_DIR=./my_data
chroma-mcp-server
```

#### Available Configuration Options

- `--client-type`: Type of Chroma client (`ephemeral`, `persistent`, `http`, `cloud`)
- `--data-dir`: Path to data directory for persistent client
- `--log-dir`: Path to log directory
- `--host`: Host address for HTTP client
- `--port`: Port for HTTP client
- `--ssl`: Whether to use SSL for HTTP client
- `--tenant`: Tenant ID for Cloud client
- `--database`: Database name for Cloud client
- `--api-key`: API key for Cloud client
- `--cpu-execution-provider`: Force CPU execution provider for embedding functions (`auto`, `true`, `false`)

### Cursor Integration

To use with Cursor, add the following to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "chroma": {
      "command": "uvx",
      "args": [
        "chroma-mcp-server"
      ],
      "env": {
        "CHROMA_CLIENT_TYPE": "persistent",
        "CHROMA_DATA_DIR": "/path/to/data/dir",
        "CHROMA_LOG_DIR": "/path/to/logs/dir",
        "LOG_LEVEL": "INFO",
        "MCP_LOG_LEVEL": "INFO"
      }
    }
  }
}
```

#### Version Management

We provide a script to manage your server version:

```bash
# Install and configure a specific version
./scripts/update_mcp_version.sh -i 0.1.4

# Only update configuration (if already installed)
./scripts/update_mcp_version.sh 0.1.4

# Use version from pyproject.toml
./scripts/update_mcp_version.sh
```

The script provides:

- One-time installation with `-i` flag
- Clean server configuration
- Automatic version detection from pyproject.toml
- Clear post-update instructions

After updating:

1. Restart Cursor to apply the changes
2. The server will start using the configured version
3. No unnecessary reinstalls on server restart

### Smithery Integration

This MCP server is compatible with [Smithery](https://smithery.ai/). See the `smithery.yaml` file for configuration details.

## Development

This project uses [Hatch](https://hatch.pypa.io/) for development and package management.

### Development Scripts

The project includes several utility scripts in the `scripts/` directory to streamline development tasks:

```bash
# Start development environment (activates Hatch shell)
./scripts/develop.sh

# Run tests with coverage
./scripts/test.sh [--coverage] [--clean]

# Build the package
./scripts/build.sh

# Publish to TestPyPI/PyPI
./scripts/publish.sh [-t|-p] [-v VERSION]

# Test UVX installation from local wheel
./scripts/test_uvx_install.sh

# Update MCP version in Cursor config
./scripts/update_mcp_version.sh [-i VERSION]
```

### Setting Up Development Environment

1. **Install Hatch:** If you don't have it, install Hatch globally:

    ```bash
    pip install hatch
    ```

2. **Activate Environment:** Use the `develop.sh` script or run `hatch shell` directly in the project root directory:

    ```bash
    # Using the script
    ./scripts/develop.sh 
    
    # Or directly with Hatch
    hatch shell
    ```

    This creates (if needed) and activates a virtual environment managed by Hatch with all development dependencies installed.

### Running Tests

Once inside the Hatch environment (activated via `hatch shell` or `./scripts/develop.sh`):

```bash
# Run all tests using pytest directly
pytest

# Or use the test script (which runs pytest via hatch)
# Exit the hatch shell first if you are inside one
./scripts/test.sh

# Run with coverage report
./scripts/test.sh --coverage

# Run specific tests
pytest tests/path/to/test_file.py::test_function
```

### Building the Package

```bash
# Build using our script (recommended)
./scripts/build.sh

# Or manually with Hatch
hatch build
```

### Publishing

```bash
# Publish to TestPyPI (for testing)
./scripts/publish.sh -t -v VERSION

# Publish to PyPI (production)
./scripts/publish.sh -p -v VERSION

# Additional options:
#  -y: Auto-confirm prompts
#  -u: PyPI username
#  -w: PyPI password/token
#  -f: Fix dependencies
```

## Dependencies

The package has optimized dependencies organized into groups:

- **Core**: Required for basic functionality (`python-dotenv`, `pydantic`, `fastapi`, `chromadb`, etc.)
- **Full**: Optional for extended functionality (`sentence-transformers`, `onnxruntime`, etc.)
- **Dev**: Only needed for development and testing

## Troubleshooting

### Common Issues

1. **Missing dependencies**: If you encounter module import errors, make sure to install all required dependencies:

   ```bash
   pip install "chroma-mcp-server[full]"
   ```

2. **Permission errors**: When using persistent storage, ensure the data directory is writable.

3. **UVX integration**: If using UVX with Cursor, make sure UVX is installed and in your PATH:

   ```bash
   pip install uv uvx
   ```

## License

MIT License (see [LICENSE](LICENSE))
