Chroma 向量存储

Install dependencies

yarn install

One-Command Installation

curl -fsSL https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/scripts/install.sh | bash

This will:

1. Download docker-compose.yml and .env.example
2. Auto-detect Docker Compose command (docker-compose or docker compose)
3. Auto-generate a secure authentication token (optional)
4. Configure ChromaDB data storage location (Docker volume, local directory, or custom path)
5. Pull Docker images
6. Display your authentication token and connection URL

Manual Installation

Option 1: Docker (Recommended - Pre-built Image)

```bash

or: docker-compose up -d (for older versions)

Start with docker-compose (builds image from source)

docker compose -f docker-compose.dev.yml up -d

or: docker-compose -f docker-compose.dev.yml up -d (for older versions)

#### Option 3: Local Development

Clone and install

git clone https://github.com/meloncafe/chromadb-remote-mcp.git cd chromadb-remote-mcp yarn install

Build and run

yarn build yarn start ```

or: docker-compose restart

```

Supported authentication methods (v2.0.0):

1. Authorization: Bearer TOKEN — only supported way to send MCP_AUTH_TOKEN.

• Recommended for service-to-service callers (API clients, scripts, MCP relays).
• Compliant with MCP specification.
• Example: curl -H "Authorization: Bearer YOUR_TOKEN" https://your-server.com/mcp

1. OAuth 2.1 / OpenID Connect — recommended for human users.

• Set OIDC_ISSUERS (comma-separated issuer URLs) or OIDC_PRESET=google,github,microsoft.
• Set OIDC_AUDIENCE to the resource identifier (typically your MCP server's public URL).
• The server publishes RFC 9728 Protected Resource Metadata at /.well-known/oauth-protected-resource.
• 401 responses include WWW-Authenticate: Bearer error="...", resource_metadata="..." per RFC 6750.

Removed in v2.0.0: X-Chroma-Token header and ?apiKey= / ?token= / ?api_key= query-parameter auth are no longer accepted. Clients that previously used those paths must migrate to Authorization: Bearer. The ALLOW_QUERY_AUTH env var is ignored.

HTTPS (Tailscale Funnel, public deployment)

client = chromadb.HttpClient( host="your-server.com", port=443, ssl=True, headers={ "Authorization": "Bearer YOUR_TOKEN" } )

Deployment

Install cloudflared

curl -L https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64 -o cloudflared chmod +x cloudflared

Start ChromaDB with Docker

docker run -d -p 8000:8000 chromadb/chroma:latest

Building from Source

```bash

Build TypeScript

yarn build

Docker Development

Local Build and Test

```bash

Build for local testing (single platform, loads to Docker)

yarn docker:build:local

Build for all platforms (amd64, arm64)

yarn docker:build

Build with custom version

./scripts/build.sh --version 1.2.3

Build with custom repository

./scripts/build.sh --repo myuser/my-mcp --version dev

#### Push to Docker Hub

4. Build Docker image

yarn docker:build:local

5. Test Docker image

docker-compose up

6. If all good, build multi-platform and push

./scripts/build.sh --version 1.2.3 --push ```

Docker Compose snippet (Gemini + Google OAuth)

services:
  mcp-server:
    image: devsaurus/chromadb-remote-mcp:2.0.0
    environment:
      EMBEDDING_PROVIDER: gemini
      EMBEDDING_MODEL: gemini-embedding-001
      EMBEDDING_DIMENSIONS: "1536"
      GEMINI_API_KEY: ${GEMINI_API_KEY}
      OIDC_PRESET: google
      OIDC_AUDIENCE: ${OIDC_AUDIENCE}  # e.g. your client_id
      CONFIDENCE_THRESHOLD: "0.55"
      RERANKER_API_BASE: "http://desktop-gpu.tail-xxxx.ts.net:8001"
      RERANKER_MODEL: bge-reranker-v2-m3

Quick Start

Method 1: Node.js (Recommended - from .env.example)

node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

Python Example

```python import chromadb

Usage

collection = client.create_collection("my_collection") collection.add( documents=["Document 1", "Document 2"], ids=["id1", "id2"] ) results = collection.query(query_texts=["query"], n_results=2)

Alternative authentication:

client = chromadb.HttpClient( host="your-server.com", port=443, ssl=True, settings=Settings( chroma_client_auth_provider="chromadb.auth.token_authn.TokenAuthClientProvider", chroma_client_auth_credentials="YOUR_TOKEN" ) ) ```

Download configuration files

mkdir chromadb-remote-mcp && cd chromadb-remote-mcp curl -O https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/docker-compose.yml curl -O https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/.env.example

Configure environment

cp .env.example .env

Edit .env and set:

Configure environment

cp .env.example .env

Edit .env with your configuration

Configure environment

cp .env.example .env

Edit .env file

Configuration

Environment Variables (.env file)

All configuration is done through the .env file. Copy .env.example to .env and customize:

cp .env.example .env

Data Storage Configuration

ChromaDB data can be stored in three ways:

1. Docker volume (default): CHROMA_DATA_PATH=chroma-data

• Managed by Docker
• Survives container restarts
• Use docker volume ls and docker volume inspect chroma-data to locate

1. Local directory: CHROMA_DATA_PATH=./data

• Easy to backup and access
• Stored in installation directory

3. Custom path: CHROMA_DATA_PATH=/path/to/data - Must be an absolute path - Useful for mounting external storage

After changing CHROMA_DATA_PATH, restart the services:

docker compose restart

---

Option 1: Tailscale VPN (Recommended)

Secure access within your Tailscale network:

```bash

Option 2: Tailscale Funnel (Public Internet)

To use Claude Desktop UI Custom Connector or share publicly:

```bash

Option 3: Cloudflare Tunnel

```bash

Option 4: Nginx Reverse Proxy

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

---

Remove existing configuration

claude mcp remove chromadb

Manual test script with options

./scripts/test.sh --help

**Integration Test Coverage:**

- ✅ Health check endpoint
- ✅ Authentication (`Authorization: Bearer` MCP_AUTH_TOKEN; OAuth 2.1 / OIDC multi-provider)
- ✅ MCP protocol (tools/list, tools/call)
- ✅ ChromaDB REST API proxy
- ✅ Collection CRUD operations
- ✅ Rate limiting
- ✅ Unauthorized access handling

**Unit Tests:**

v2.0.0 Configuration

v2.0 introduces collection metadata schema v2, OAuth 2.1 OIDC, configurable embedding providers, and an optional reranker. See MIGRATION.md for the upgrade guide.

Environment variables

API Endpoints

Server Endpoints

• MCP: http://localhost:8080/mcp (via Caddy proxy)
• Health: http://localhost:8080/health
• ChromaDB API: http://localhost:8080/api/v2/*
• Swagger UI: http://localhost:8080/docs

---

API Documentation

Visit https://your-server.com/docs for Swagger UI documentation of all ChromaDB REST API endpoints.

---

MCP endpoint (Bearer token)

curl -X POST https://your-server.com/mcp \ -H "Content-Type: application/json" \ -H "Authorization: Bearer YOUR_TOKEN" \ -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

MCP endpoint (Bearer token)

curl -X POST "https://your-server.com/mcp" \ -H "Authorization: Bearer YOUR_TOKEN" \ -H "Content-Type: application/json" \ -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

ChromaDB REST API

curl https://your-server.com/api/v2/heartbeat \ -H "Authorization: Bearer YOUR_TOKEN"

Run all tests (unit + integration)

yarn test:all ```

Unit Test Coverage:

• ✅ Authentication utilities (timing-safe comparison, buffer operations)
• ✅ Input validation (collection names, document IDs, metadata)
• ✅ Data processing (response formatting, JSON serialization)
• ✅ Error message formatting

See __tests__/README.md for detailed testing strategy.

3. Run integration tests

yarn test

Troubleshooting