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

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

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

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.

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

1. Local directory: CHROMA_DATA_PATH=./data

• Easy to backup and access
• Stored in installation directory

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

Deploying with deploy.sh

deploy.sh wraps the Docker Compose lifecycle of this repository's docker-compose.yml in one script. It is host independent: everything host specific lives in .env (see .env.example) and optional extra compose files, never in the script.

./deploy.sh help prints the usage.

Settings — read from the host's .env (a process environment variable of the same name takes precedence):

DRY_RUN=1, DEPLOY_DIR=<dir> (target directory, for tests) and CHROMA_IMAGE=<ref> (image for the backup tar when no chromadb container exists) are read from the process environment.

One stack per host — docker-compose.yml fixes container_name (chromadb, chroma-mcp-server, caddy-proxy), so changing only COMPOSE_PROJECT_NAME does not let a second stack run on the same host: the container names collide.

Compose file selection — COMPOSE_FILE is a list merged in order (later files override earlier ones), exactly like docker compose. Relative entries resolve against the deploy directory, absolute entries are used unchanged. deploy.sh passes --project-directory on every call, so .env and relative paths always refer to the deploy directory.

`DRY_RUN=1` — prints every docker command prefixed [DRY-RUN], calls no docker and changes no file; it works even without docker installed. install prints its plan without copying .env or creating backups/; version / update skip the digest judgment, the .env write and the mcp-server recreation. A missing .env is downgraded to a warning: the plan is printed from the committed .env.example / compose defaults and no file is created. Without DRY_RUN, a missing .env is still an error.

DRY_RUN=1 ./deploy.sh update

Output language — help and log messages are English or Korean. The language is DEPLOY_LANG (environment, then .env); if unset, the first non-empty of LC_ALL, LC_MESSAGES, LANG: a value starting with ko selects Korean, anything else English.

`CHROMA_SERVER_VERSION` handling — the Chroma server reports a hardcoded 1.0.0, so update / version compare the RepoDigest of the chromadb container's image with the digest pinned in the compose file and then with the Docker Hub digest of the pinned tag, and record the result in .env. When the value changed, mcp-server alone is recreated with up -d. If the version cannot be determined (including a match on the Docker Hub latest tag alone), an existing .env value is preserved with a warning; unknown is written only when no value exists yet.

Backup — ./deploy.sh backup reads the data through a throwaway container with a read-only mount, so root-owned bind directories and named volumes both work. The data location is detected automatically: the existing chromadb container's /data mount first, otherwise CHROMA_DATA_PATH from .env (an absolute, ./ or ../ path is a bind mount; a bare name — the default chroma-data — is the compose named volume <project>_<name>). The archive is written as .tar.gz.partial and renamed on success (removed on failure). chromadb is stopped for a consistent snapshot and started again only if it was running before the backup. If the backup receives SIGINT or SIGTERM (for example Ctrl+C), it removes the .tar.gz.partial file, starts chromadb again when it was running before the backup, and exits with code 130 (SIGINT) or 143 (SIGTERM).

Self-update — ./deploy.sh self-update [tag] downloads the repository-managed files from a GitHub release tag (default: the latest release; DEPLOY_TAG or --tag also work) into a staging directory, validates them (non-empty, bash -n for the script, services: for compose files, and SHA256SUMS when the release publishes one), backs up the current files to backups/self-update_<timestamp>_<version>/, replaces each file atomically (temp file + mv), and restores the backup on any failure or interrupt. It shows the current and target version (the installed tag is recorded in .deploy-release). .env, local compose overrides that are not part of the release, and the data directory are never touched. It refuses to run inside a git checkout (use git pull) and supports DRY_RUN=1. DEPLOY_REPO (default meloncafe/chromadb-remote-mcp) and SELF_UPDATE_FILES override the source repository and the file list. update (images) and self-update (scripts/compose) are deliberately separate: swapping the compose file in the middle of update would change what the pull/recreate runs against, so update only prints a hint and self-update ends by telling you to run update.

Behind a Traefik reverse proxy — docker-compose.traefik.example.yml is an optional example override with placeholder variables. Copy it, keep the copy on the server, and select it through the compose file list in .env:

cp docker-compose.traefik.example.yml docker-compose.traefik.yml

# .env
COMPOSE_FILE=docker-compose.yml:docker-compose.traefik.yml
TRAEFIK_HOST=mcp.example.com
TRAEFIK_CERT_RESOLVER=your-resolver

./deploy.sh update

TRAEFIK_HOST and TRAEFIK_CERT_RESOLVER are required. Optional: TRAEFIK_NETWORK (external network Traefik is attached to, which must already exist; default traefik), TRAEFIK_ENTRYPOINT (default websecure), TRAEFIK_MIDDLEWARES (comma-separated; see the note below) and TRAEFIK_ROUTER_NAME (default chromadb-mcp). Traefik router and service names are global, so pick a TRAEFIK_ROUTER_NAME that no other container on that Traefik already uses. The example removes the base file's host port mapping with !reset, which requires Docker Compose 2.24 or newer.

The middlewares label in docker-compose.traefik.example.yml is commented out by default, so no middleware is attached. Once you uncomment the label, TRAEFIK_MIDDLEWARES becomes required: not only an unset variable but also an empty value (TRAEFIK_MIDDLEWARES=) aborts with required variable TRAEFIK_MIDDLEWARES is missing a value. To run without middlewares, keep the label commented out.

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

1. Use HTTPS

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

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

1. Monitor Access

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

1. 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/:

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
├── CHANGELOG.ko.md          # Version history (Korean)
└── 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

Recommended embedding + reranker combinations

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

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.