ChromaDB Remote MCP Server

What is ChromaDB Remote MCP Server?

A Streamable HTTP MCP server that proxies all ChromaDB CRUD and search operations, exposing them through the Model Context Protocol. It enables Claude (Desktop, Mobile, Code) and any MCP‑compatible client to read and write the same vector database without exposing ChromaDB directly.

How to use ChromaDB Remote MCP Server?

1. Deploy – run the provided docker-compose.yml (or build from source) which starts the MCP server, a Caddy reverse proxy, and a ChromaDB container.
2. Configure authentication – set a strong MCP_AUTH_TOKEN (or OIDC) in the .env file.
3. Add the server to Claude:
   • Desktop/Mobile: Settings → Integrations → Custom Connector → URL https://<host>/mcp with header Authorization: Bearer <TOKEN>.
   • Claude Code: claude mcp add --transport http chromadb https://<host>/mcp --header "Authorization: Bearer <TOKEN>".
4. Access from Python or other tools – use the proxied REST API at https://<host>/api/v2/* with the same Authorization header.

Key Features

• Unified memory across all Claude clients (Desktop, Mobile, Code).
• Full CRUD support for ChromaDB collections and documents via MCP tools.
• Optional REST API proxy for direct Python/JS access.
• Single‑token authentication protecting both MCP and REST endpoints.
• Docker‑first deployment with one‑command installer.
• Origin‑header validation and rate‑limiting for security.
• Support for OAuth 2.1 / OIDC in addition to static bearer tokens.

Use Cases

• Cross‑device AI assistants – keep personal knowledge consistent between Claude desktop and mobile.
• RAG pipelines – let server‑side code query the same vector store that Claude uses for context.
• Team shared memory – multiple developers can store and retrieve embeddings from a central ChromaDB.
• Secure private retrieval – expose only the MCP layer to the internet while keeping ChromaDB on a private network.

FAQ

Q: Do I need to expose ChromaDB directly? A: No. The MCP server acts as a protected gateway; ChromaDB remains bound to localhost inside Docker.

Q: Can I use the server without authentication? A: In a Tailscale VPN it works without a token, but the server now refuses to start without an auth method unless ALLOW_INSECURE_NO_AUTH=true is set.

Q: How do I generate a secure token? A: node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))" or openssl rand -base64 32 | tr '+/' '-_' | tr -d '='.

Q: What if I want direct REST access? A: Enable CHROMA_REST_PROXY_ENABLED=true in .env; the proxy then requires the same bearer token and validates Origin headers.

Q: Which clients are supported? A: Any MCP‑compatible client – Claude Desktop, Claude Mobile, Claude Code, Gemini CLI, Cursor, VS Code Copilot, plus custom scripts using the MCP SDK.

ChromaDB Remote MCP Server

A Streamable HTTP MCP (Model Context Protocol) server that provides remote access to ChromaDB for AI assistants like Claude. Enables semantic search and vector database operations from mobile devices and remote locations.

Note: This project uses MCP Streamable HTTP (2025-03-26 spec). SSE transport is deprecated.

한국어 문서

---

Cross-Platform AI Memory Server

Compatible with ALL major AI platforms:

• Claude (Desktop, Mobile, Code)
• Gemini (CLI, Code Assist)
• Cursor, Cline, Windsurf, VS Code Copilot
• and use Remote MCP with any other MCP-compatible client

Features

Remote MCP server that enables all Claude clients (Desktop, Code, Mobile) to access the same self-hosted ChromaDB instance.

• Shared Memory Across Devices - All Claude clients use the same ChromaDB instance
• Self-Hosted & Private - Your data stays on your infrastructure
• Remote Access - Connect from anywhere via Tailscale or public internet
• Complete ChromaDB Support - All CRUD operations via MCP tools
• REST API Proxy - Direct ChromaDB access for Python/JavaScript
• Unified Authentication - Single token protects both MCP and REST API endpoints
• Easy Deployment - One-command installation with Docker

---

Architecture

Overview

┌──────────────────────────────┐      ┌──────────────┐
│   Claude Desktop + Mobile    │      │  Claude Code │
│  (Custom Connector - synced) │      │  (CLI setup) │
└──────────────┬───────────────┘      └──────┬───────┘
               │                             │
               │     MCP Remote Connector    │
               └─────────────┬───────────────┘
                             │ HTTPS
                   ┌─────────▼──────────┐
                   │   Remote MCP       │
                   │   Server (Node.js) │
                   │                    │
                   │ • Auth Gateway     │
                   │ • MCP Protocol     │
                   │ • REST API Proxy   │
                   └─────────┬──────────┘
                             │
                   ┌─────────▼──────────┐
                   │     ChromaDB       │
                   │ (Vector Database)  │
                   │                    │
                   │ • Embeddings       │
                   │ • Collections      │
                   │ • Semantic Search  │
                   └────────────────────┘

How Clients Connect:

• Claude Desktop + Mobile: Set up once using custom connector in Claude Desktop, and it automatically syncs to the mobile app. Both share the same connection automatically.
• Claude Code: Requires separate setup using claude mcp add CLI command.

All clients access the same self-hosted ChromaDB through this remote MCP server. Vector embeddings and semantic search results persist across all platforms.

API Endpoints

Path	Purpose	Client	Authentication
/mcp	MCP Protocol	Claude Desktop/Code/Mobile	✅
/api/v2/*	ChromaDB REST API	Python	✅
/docs	Swagger UI	Browser (API docs)	✅
/openapi.json	OpenAPI Spec	API tools	✅
/health	Health check	Monitoring	❌

How It Works

1. Claude Desktop/Mobile: Add MCP server via custom connector (syncs automatically between devices)
2. Claude Code: Add MCP server using claude mcp add CLI command
3. Remote MCP Server authenticates requests and translates MCP protocol to ChromaDB operations
4. ChromaDB stores and retrieves vector embeddings for semantic search
5. Python can also access ChromaDB directly via the proxied REST API

Benefits:

• Same vector database across all clients
• Desktop and mobile share connection automatically
• Self-hosted and private
• Persistent memory across app restarts
• Single source of truth for embeddings

---

Quick Start

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)

# 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:
#   - MCP_AUTH_TOKEN (see token generation below)
#   - PORT (default: 8080)
#   - CHROMA_DATA_PATH (default: chroma-data)

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

# Check health
curl http://localhost:8080/health

# View logs
docker compose logs -f

Option 2: Build from Source

# Clone repository
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp

# Configure environment
cp .env.example .env
# Edit .env with your configuration

# 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

# Configure environment
cp .env.example .env
# Edit .env file

# Build and run
yarn build
yarn start

Generate Secure Token

For production use, generate a secure token for MCP_AUTH_TOKEN in .env:

# Method 1: Node.js (Recommended)
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# Method 2: OpenSSL
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

Copy the generated token and paste it into your .env file:

MCP_AUTH_TOKEN=your-generated-token-here

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

---

Configuration

Environment Variables (.env file)

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

cp .env.example .env

Variable	Description	Default	Required
PORT	External port (Caddy reverse proxy)	8080	No
CHROMA_DATA_PATH	ChromaDB data storage path (volume name, ./data, or absolute path)	chroma-data	No
CHROMA_HOST	ChromaDB host (internal)	chromadb	No
CHROMA_PORT	ChromaDB port (internal)	8000	No
CHROMA_TENANT	ChromaDB tenant	default_tenant	No
CHROMA_DATABASE	ChromaDB database	default_database	No
MCP_AUTH_TOKEN	Authentication token for MCP and REST API	-	Yes (for public access)
CHROMA_AUTH_TOKEN	ChromaDB auth token (if ChromaDB requires auth)	-	No
RATE_LIMIT_MAX	Max requests per IP per 15 minutes	100	No
ALLOWED_ORIGINS	Comma-separated list of allowed origins (DNS rebinding protection)	-	No

Authentication

IMPORTANT: For public internet access (Tailscale Funnel, Cloudflare Tunnel, etc.), you must set MCP_AUTH_TOKEN in your .env file.

Generate a secure token:

# Method 1: Node.js (Recommended - from .env.example)
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

# Method 2: OpenSSL
openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

Edit your .env file:

MCP_AUTH_TOKEN=your-generated-token-here

Then restart the services:

docker compose restart
# 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

2. 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.

Origin Header Validation (DNS Rebinding Protection)

The server validates the Origin header for browser requests to prevent DNS rebinding attacks. This security feature is enabled by default and protects your local MCP server from malicious websites.

Default allowed origins (always permitted):

• Localhost variants: localhost, 127.0.0.1, [::1]
• Claude.ai domains: https://claude.ai, https://api.anthropic.com

Configure additional allowed origins:

If you need to allow additional web applications or custom domains, add them to ALLOWED_ORIGINS in your .env file:

# Add additional custom domains (Claude.ai is already allowed by default)
ALLOWED_ORIGINS=https://myapp.com,https://yourdomain.com

When to configure ALLOWED_ORIGINS:

• ✅ Using Claude Desktop Custom Connector → No configuration needed (allowed by default)
• ✅ Accessing from custom web applications → Add your application's domain
• ✅ Using Swagger UI remotely → Add your server's domain
• ❌ Using Claude Code CLI → Not needed (no Origin header)
• ❌ Using Python/JavaScript clients → Not needed (no Origin header)
• ❌ Local development only → Not needed (localhost is allowed by default)

Example configurations:

# For custom web application
ALLOWED_ORIGINS=https://myapp.com,https://app.mycompany.com

# Multiple custom domains (comma-separated, spaces are trimmed)
ALLOWED_ORIGINS=https://myapp.com, https://api.example.com, https://dashboard.mycompany.com

# Leave empty if you only need Claude.ai and localhost
ALLOWED_ORIGINS=

Note: Claude.ai domains (https://claude.ai, https://api.anthropic.com) and localhost are always allowed, even if ALLOWED_ORIGINS is empty. Server-to-server requests (without Origin header) are always permitted.

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

2. 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

---

Connecting Claude

Claude Desktop + Mobile

Method 1: Custom Connector (Recommended - Pro/Team/Enterprise)

1. Open Claude Desktop → Settings → Integrations → Custom Connector
2. Click "Add Custom Server"
3. Enter:
   • Name: ChromaDB
   • URL: https://your-server.com/mcp (set Authorization: Bearer YOUR_TOKEN in the connector's header config)

Note: Custom connector automatically syncs to the mobile app. Authentication is mandatory for remote access.

Method 2: mcp-remote Wrapper (Free/Pro Users)

If you don't have access to Custom Connectors, use the mcp-remote package as a workaround:

Configuration file location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

Add to configuration file:

{
  "mcpServers": {
    "chromadb": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-server.com/mcp", "--header", "Authorization: Bearer YOUR_TOKEN"]
    }
  }
}

Restart Claude Desktop after editing the file.

Important: Remote MCP servers cannot be configured directly in claude_desktop_config.json using streamableHttp transport. You must either use Custom Connectors or the mcp-remote wrapper package.

Claude Code

CLI Command:

# Without authentication
claude mcp add --transport http chromadb https://your-server.com/mcp

# With authentication (Query Parameter - Recommended)
claude mcp add --transport http chromadb https://your-server.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# With authentication (Header)
claude mcp add --transport http chromadb https://your-server.com/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Verify
claude mcp list

---

Available Tools (v2.2.0)

The MCP server provides these tools for Claude. v2.2.0 expands coverage to 30 tools across collection / document / search / fork / client-info / admin / destructive groups.

Collection Management

• chroma_list_collections - List all collections (with limit / offset)
• chroma_create_collection - Create a new collection (configuration / schema optional)
• chroma_get_or_create_collection - Idempotent create-or-get (v2.2.0)
• chroma_modify_collection - Rename / change metadata or configuration (v2.2.0)
• chroma_delete_collection - Delete a collection
• chroma_get_collection_info - Get collection metadata
• chroma_get_collection_count - Get document count (read_level optional)
• chroma_count_collections - Total collection count (v2.2.0)
• chroma_peek_collection - Preview collection contents

Document Operations

• chroma_add_documents - Add documents (with uris for multi-modal)
• chroma_upsert_documents - Idempotent insert-or-update (v2.2.0)
• chroma_query_documents - Semantic search (with query_uris / ids pre-filter)
• chroma_get_documents - Retrieve documents (read_level optional)
• chroma_update_documents - Update existing documents (with embeddings / uris)
• chroma_delete_documents - Delete by ids and/or where / where_document filter

Server Info (v2.2.0)

• chroma_heartbeat - Server heartbeat (nanosecond timestamp)
• chroma_get_server_version - Server version string
• chroma_get_max_batch_size - Max batch size (for client-side splitting)
• chroma_get_user_identity - Current tenant + databases

Distributed/Cloud-only — opt-in (CHROMA_DISTRIBUTED_TOOLS_ENABLED=true)

These 4 tools require ChromaDB's distributed executor (the executor is the chromadb-server-internal frontend layer, not an algorithmic distribution requirement). The single-node open-source server (chromadb/chroma:latest docker) ships with the local executor, which has these methods hard-coded as unimplemented in rust/frontend/src/executor/local.rs and rust/types/src/api_types.rs. To use them you need either Chroma Cloud (CloudClient) or a self-hosted distributed Chroma deployment (Kubernetes multi-component: frontend + query executor + WAL + compactor + object storage).

Hidden by default so single-node deployments don't waste LLM context on tools that always return "not implemented for local executor" / "unsupported for local chroma".

• chroma_search - Hybrid dense + sparse search (RRF). The algorithm itself works on a single node; chromadb open-source simply hasn't implemented the search() endpoint in the local executor.
• chroma_fork_collection - Zero-copy fork (segment-level operation on object storage — architecturally requires the distributed compactor/storage stack).
• chroma_get_fork_count - Fork metadata lookup (depends on the distributed metadata store).
• chroma_get_indexing_status - WAL offset + compactor index progress (requires the distributed WAL/compactor services).

Admin — opt-in (CHROMA_ADMIN_TOOLS_ENABLED=true)

• chroma_admin_create_database / chroma_admin_get_database / chroma_admin_list_databases
• chroma_admin_create_tenant / chroma_admin_get_tenant

Destructive — opt-in (CHROMA_ALLOW_DESTRUCTIVE_OPS=true)

Calls emit a [DESTRUCTIVE] audit line.

• chroma_reset_database - Reset entire database (irreversible)
• chroma_admin_delete_database - Delete a database (requires both flags)

---

Using ChromaDB from Python

The MCP server proxies all ChromaDB REST API endpoints, allowing direct access from Python clients.

Python Example

import chromadb

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

# Local development (HTTP)
client = chromadb.HttpClient(
    host="localhost",
    port=8080,
    ssl=False,
    headers={
        "Authorization": "Bearer YOUR_TOKEN"
    }
)

# 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:

from chromadb.config import Settings

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"
    )
)

API Documentation

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

---

Deployment

Option 1: Tailscale VPN (Recommended)

Secure access within your Tailscale network:

# Start services
docker compose up -d

# Enable Tailscale Serve (HTTPS with automatic certificates)
tailscale serve https / http://127.0.0.1:8080

# Check status
tailscale serve status

Your server is now accessible at https://your-machine.tailXXXXX.ts.net to all devices in your Tailnet.

Advantages:

• Automatic HTTPS certificates
• No public internet exposure
• Encrypted VPN tunnel
• Authentication optional (VPN provides security layer)

Option 2: Tailscale Funnel (Public Internet)

To use Claude Desktop UI Custom Connector or share publicly:

# Enable Funnel (allows public internet access)
tailscale funnel 8080 on
tailscale serve https / http://127.0.0.1:8080

# Verify Funnel is active
tailscale serve status  # Should show "Funnel on"

Warning: This exposes your server to the public internet. Authentication is mandatory! Set MCP_AUTH_TOKEN in your environment.

Disable Funnel:

tailscale funnel 8080 off

Option 3: Cloudflare Tunnel

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

# Authenticate
./cloudflared tunnel login

# Create tunnel
./cloudflared tunnel create chroma-mcp

# Run tunnel
./cloudflared tunnel --url http://localhost:3000

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;
    }
}

---

Security

Code Quality & Security Analysis

This project follows strict security practices and has resolved all security issues identified by static analysis:

• ✅ Zero Active Issues: All OWASP and CWE security findings have been resolved
• 🔒 Static Analysis: Continuous monitoring with DeepSource
• 🛡️ Security Standards: Compliant with OWASP Top 10 and Node.js security best practices
• 📊 Automated Scanning: Dependabot, CodeQL, and container vulnerability scanning

For detailed security information, see Security Policy.

Security Recommendations

1. Enable Authentication for Public Access

   • Set MCP_AUTH_TOKEN when using Tailscale Funnel or public internet
   • Generate strong tokens: openssl rand -base64 32 | tr '+/' '-_' | tr -d '='
   • Rotate tokens regularly

2. Use HTTPS

   • Tailscale provides automatic HTTPS certificates
   • Use reverse proxy (Nginx/Caddy) with Let's Encrypt for other deployments

3. Prefer VPN Over Public Internet

   • Tailscale Serve (VPN-only) is more secure than Funnel (public)
   • Authentication is optional within VPN but mandatory for public access

4. Monitor Access

   # Check for unauthorized access attempts
   docker compose logs mcp-server | grep "Unauthorized"
   

5. Network Isolation

   • Keep ChromaDB on private network
   • Only expose MCP server to public internet

---

Testing

Local Testing

# Health check
curl http://localhost:3000/health

# MCP tools list
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# ChromaDB heartbeat
curl http://localhost:3000/api/v2/heartbeat

Remote Testing (with authentication)

# 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"

# Swagger UI (browser)
https://your-server.com/docs  # send Authorization: Bearer YOUR_TOKEN header

---

Troubleshooting

ChromaDB Connection Failed

# Check if ChromaDB is running
curl http://localhost:8000/api/v2/heartbeat

# Start ChromaDB with Docker
# WARNING: ChromaDB has no built-in authentication — do not publish on routable interface.
# Bind to loopback only (127.0.0.1:8000:8000). Use MCP server as the authenticated gateway.
docker run -d -p 127.0.0.1:8000:8000 chromadb/chroma:1.5.9

# Check MCP server logs
docker compose logs mcp-server

MCP Server Not Responding

# Check logs
docker compose logs mcp-server

# Check port conflicts
lsof -i :3000

# Restart services
docker compose restart

Claude Desktop Connection Issues

1. Restart Claude Desktop
2. Verify URL includes /mcp path
3. Confirm transport type is streamableHttp (not sse)
4. Check authentication token if enabled
5. For Custom Connector: Ensure Tailscale Funnel is active

TLS Handshake Timeout on Local Network

If you're connecting from the same local network as the server and using Tailscale Funnel HTTPS:

Problem: TLS handshake fails with timeout when accessing https://your-server.ts.net from the same network.

Root cause: Tailscale Funnel has issues with TLS termination when clients on the same LAN try to connect via the public Funnel domain.

Solution: Use direct local network connection instead of Tailscale HTTPS:

# Remove existing configuration
claude mcp remove chromadb

# Add with local IP address
claude mcp add chromadb --transport http \
  http://192.168.x.x:8080/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

# Or use hostname if DNS resolves
claude mcp add chromadb --transport http \
  http://server-hostname:8080/mcp \
  --header "Authorization: Bearer YOUR_TOKEN"

Verification:

# Test local network connection
curl http://192.168.x.x:8080/health

# Should return: {"status":"ok","service":"chroma-remote-mcp",...}

Note: External clients should continue using Tailscale Funnel HTTPS. This issue only affects clients on the same LAN as the server.

Authentication Errors (401)

# Verify MCP_AUTH_TOKEN is set
docker compose exec mcp-server env | grep MCP_AUTH_TOKEN

# Test without token (should fail with 401)
curl -X POST https://your-server.com/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# Test with correct token (should succeed)
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}'

---

Development

Building from Source

# Clone repository
git clone https://github.com/meloncafe/chromadb-remote-mcp.git
cd chromadb-remote-mcp

# Install dependencies
yarn install

# Development mode (auto-reload)
yarn dev

# Build TypeScript
yarn build

# Type check
yarn type-check

Testing

The project includes integration tests with Docker-based E2E validation:

# Run all tests (starts services, runs tests, cleans up)
yarn test

# Run tests and keep containers running for debugging
yarn test:keep

# 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:

# Run unit tests
yarn test:unit

# Run with watch mode
yarn test:unit:watch

# Run with coverage
yarn test:unit:coverage

# 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.

Code Quality & Coverage

This project uses Codecov for code coverage tracking and test analytics.

Docker Development

Local Build and Test

# Build for local testing (single platform, loads to Docker)
yarn docker:build:local

# Or with script directly
./scripts/build.sh --platform linux/amd64 --load

# Test the built image
docker run -p 3000:3000 \
  -e MCP_AUTH_TOKEN=test123 \
  devsaurus/chromadb-remote-mcp:latest

Multi-Platform Build

# 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

# Push latest tag
yarn docker:push

# Push specific version
VERSION=1.2.3 yarn docker:push

# Or with script directly
./scripts/build.sh --version 1.2.3 --push

# With custom repository
DOCKER_REPO=myuser/my-mcp ./scripts/build.sh --version 1.2.3 --push

Environment Variables for Docker Scripts:

export DOCKER_REPO=myuser/my-mcp       # Docker repository
export VERSION=1.2.3                    # Image version tag
export DOCKER_USERNAME=myuser           # For push authentication
export DOCKER_PASSWORD=mytoken          # Docker Hub token

Development Scripts

All development scripts are located in scripts/:

Script	Purpose	Usage
build.sh	Build and push Docker images	./scripts/build.sh --help
test.sh	Run integration tests	./scripts/test.sh --help
install.sh	One-command installation	curl ... | bash

Quick Development Workflow:

# 1. Make code changes
vim src/index.ts

# 2. Test locally
yarn dev

# 3. Run integration tests
yarn test

# 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

Project Structure

chromadb-remote-mcp/
├── .github/
│   ├── ISSUE_TEMPLATE/       # GitHub issue templates
│   └── workflows/            # GitHub Actions (publish-release, security-scan, chromadb-version-check.yml)
├── scripts/
│   ├── build.sh             # Docker build and push script (multi-platform)
│   ├── test.sh              # Integration test runner
│   └── install.sh           # One-command installation
├── src/
│   ├── index.ts             # Main server entry point
│   ├── chroma-tools.ts      # MCP tool definitions and handlers
│   └── types.ts             # TypeScript type definitions
├── docker-compose.yml       # Production (prebuilt image)
├── docker-compose.dev.yml   # Development (builds from source)
├── Dockerfile               # MCP server Docker image
├── .env.example             # Environment variables template
├── package.json             # Node.js dependencies
├── tsconfig.json            # TypeScript configuration
├── SECURITY.md              # Security policy
├── CONTRIBUTING.md          # Contribution guidelines
├── CODE_OF_CONDUCT.md       # Code of conduct
├── CHANGELOG.md             # Version history
└── LICENSE                  # MIT license

---

v2.2.3 Release Notes — CVE-2026-45829 Security Hardening

⚠️ Breaking changes — operators upgrading from v2.2.2 or earlier must read this section.

ChromaDB image version pinned (R4)

All docker-compose*.yml files now pin chromadb/chroma to version 1.5.9@sha256:.... Versions 1.0.0–1.5.8 are vulnerable to CVE-2026-45829 (ChromaToast, CVSS 10.0) — a pre-auth RCE via malicious embedding-function configuration. Do not downgrade the pin.

A CI workflow (.github/workflows/chromadb-version-check.yml) fails the build if any docker-compose file references a version in the vulnerable range.

Dev fail-open removed (R1, breaking)

Previously, starting the server without MCP_AUTH_TOKEN or OIDC_ISSUERS/OIDC_PRESET would succeed silently in non-production environments. This behaviour is removed.

The server now refuses to start unless at least one auth method is configured or ALLOW_INSECURE_NO_AUTH=true is explicitly set.

Migration:

• Production: set MCP_AUTH_TOKEN or configure OIDC.
• Local dev: add ALLOW_INSECURE_NO_AUTH=true to your .env.

ChromaDB REST catch-all proxy is now OFF by default (R3, breaking)

The pass-through REST proxy (previously always mounted) is now disabled unless CHROMA_REST_PROXY_ENABLED=true is set. When disabled, all /api/* requests return 404.

When enabled, the proxy enforces:

• DNS-rebind protection (validateOriginHeader) — Origin: evil.example → 403
• Authentication (always required; ALLOW_INSECURE_NO_AUTH does not bypass the proxy)
• Path filter: collection create/modify/delete and embedding-function endpoints are blocked (403)
• Body sanitize: configuration.embedding_function in POST/PUT/PATCH body → 400

Migration: If you relied on direct /api/v2/* REST passthrough, set CHROMA_REST_PROXY_ENABLED=true and ensure authentication is configured.

---

Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

License

MIT License

---

Resources

• MCP Specification
• MCP TypeScript SDK
• ChromaDB Documentation
• Tailscale Serve
• Tailscale Funnel
• Cloudflare Tunnel

---

Support

If you encounter any issues or have questions, please open an issue.

---

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

Variable	Purpose
EMBEDDING_PROVIDER	chromadb-default (English-only, default) / external / openai_compatible / gemini / voyage
EMBEDDING_MODEL	Provider-specific model id. Stored in collection metadata.
EMBEDDING_DIMENSIONS	Vector dimensions. Required for external mode; Gemini accepts 768/1536/3072.
EMBEDDING_API_BASE	OpenAI-compatible endpoint base URL (Ollama / TEI / Voyage / Together / vLLM).
EMBEDDING_API_KEY	Bearer key for openai_compatible or voyage providers.
GEMINI_API_KEY	Google AI Studio API key for the gemini provider.
CONFIDENCE_THRESHOLD	Default min_score (0-1). Tool argument has priority.
RERANKER_API_BASE	OpenAI-compatible /rerank endpoint. Reranker is fail-soft.
RERANKER_API_KEY	Optional bearer key for the reranker.
RERANKER_MODEL	Reranker model id (default bge-reranker-v2-m3).
OIDC_ISSUERS	Comma-separated OIDC issuer URLs.
OIDC_PRESET	Convenience preset names: google,github,microsoft.
OIDC_AUDIENCE	Expected aud claim.
OIDC_SCOPES	Comma-separated scopes for the Protected Resource Metadata.
OIDC_LOG_SUB_MODE	full for raw sub, otherwise SHA-256 first 12 chars (default).
MCP_AUTH_TOKEN	Service-to-service / CI / internal scripts only. Use OAuth for human users. Coexists with OIDC — either method accepts.
LEGACY_COLLECTION_COMPAT	true to allow read-only access to legacy v1 collections. Writes are still rejected.

Recommended embedding + reranker combinations

Verified locally on Korean RAG workloads (2026-05). Pick by priority:

Priority	Embedding	Reranker	Why
Accuracy first (recommended)	gemini / gemini-embedding-001 / 1536d	cohere / rerank-multilingual-v3.0	Gemini emits asymmetric query↔document vectors (RETRIEVAL_QUERY/RETRIEVAL_DOCUMENT, self-distance ≈ 0.21 in our test); Cohere reorders short KR question↔answer pairs cleanly.
Cost-balanced	voyage / voyage-3 / 1024d	cohere / rerank-multilingual-v3.0	Voyage embeddings are ~1/2.5 the cost of Gemini and still asymmetric (input_type query/document, self-distance ≈ 0.56).
Minimum embedding cost	openai_compatible / text-embedding-3-small / 1536d	cohere / rerank-multilingual-v3.0	Cheapest hosted embedding; symmetric vectors are weaker on short KR queries, so the reranker is essential.
Self-hosted / offline	openai_compatible (Ollama / TEI / vLLM)	TEI bge-reranker-v2-m3 or similar	No external API; latency depends on local hardware.

Notes from the verification run:

• Voyage rerank-2 did NOT reorder the short KR question↔answer pair used in this test — keep Cohere as the rerank default for KR until your own corpus shows otherwise.
• The reranker layer is fail-soft: leave RERANKER_API_BASE unset to disable reranking without code changes.
• Set CONFIDENCE_THRESHOLD (or per-call min_score) to drop low-similarity hits; the server emits confidence_gate: "no_confident_match" when every result is filtered.

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

OAuth flow

1. Configure your IdP (Google / GitHub / Microsoft) to issue tokens for an audience that matches OIDC_AUDIENCE.
2. Set OIDC_PRESET=google (or OIDC_ISSUERS=... for custom IdPs) and OIDC_AUDIENCE=....
3. Clients send Authorization: Bearer <token> to /mcp.
4. 401 responses include WWW-Authenticate: Bearer error="...", resource_metadata="<base>/.well-known/oauth-protected-resource" per RFC 9728.
5. MCP_AUTH_TOKEN remains valid alongside OAuth — recommended for non-interactive workloads.

Reading legacy v1 collections

Set LEGACY_COLLECTION_COMPAT=true to allow read-only access. Writes (chroma_add_documents / update / delete) on v1 collections still return Error: Cannot write to legacy v1 collection. See MIGRATION.md.