Potencia tu agente
La URL propia del publicador. No es un endpoint de PlugMCP.
Host a copy with our keys and logs.
https://meloncafe.github.io/chromadb-remote-mcp/mcpEl botón de Claude de arriba abre Claude con el nombre y la URL ya rellenados. Aún tienes que confirmarlo allí.
claude mcp add --transport http io.github.meloncafe-chromadb-remote-mcp https://meloncafe.github.io/chromadb-remote-mcp/mcpRun in a terminal.
{ "mcpServers": { "io.github.meloncafe-chromadb-remote-mcp": { "command": "npx", "args": [ "-y", "mcp-remote", "https://meloncafe.github.io/chromadb-remote-mcp/mcp" ] } }}claude_desktop_config.json
¿URL remota o un comando en tu máquina? En qué se diferencian las dos instalaciones
Ejecutar en PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirA 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.
Compatible with ALL major AI platforms:
Remote MCP server that enables all Claude clients (Desktop, Code, Mobile) to access the same self-hosted ChromaDB instance.
┌──────────────────────────────┐ ┌──────────────┐
│ 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 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.
claude mcp add CLI commandBenefits:
curl -fsSL https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/scripts/install.sh | bash
This will:
docker-compose.yml and .env.exampledocker-compose or docker compose)# 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
# 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)
# 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
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
http://localhost:8080/mcp (via Caddy proxy)http://localhost:8080/healthhttp://localhost:8080/api/v2/*http://localhost:8080/docsAll configuration is done through the .env file. Copy .env.example to .env and customize:
cp .env.example .env
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):
Authorization: Bearer TOKEN — only supported way to send MCP_AUTH_TOKEN.
curl -H "Authorization: Bearer YOUR_TOKEN" https://your-server.com/mcpOAuth 2.1 / OpenID Connect — recommended for human users.
OIDC_ISSUERS (comma-separated issuer URLs) or OIDC_PRESET=google,github,microsoft.OIDC_AUDIENCE to the resource identifier (typically your MCP server's public URL)./.well-known/oauth-protected-resource.WWW-Authenticate: Bearer error="...", resource_metadata="..." per RFC 6750.Removed in v2.0.0:
X-Chroma-Tokenheader and?apiKey=/?token=/?api_key=query-parameter auth are no longer accepted. Clients that previously used those paths must migrate toAuthorization: Bearer. TheALLOW_QUERY_AUTHenv var is ignored.
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, 127.0.0.1, [::1]https://claude.ai, https://api.anthropic.comConfigure 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:
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.
ChromaDB data can be stored in three ways:
Docker volume (default): CHROMA_DATA_PATH=chroma-data
docker volume ls and docker volume inspect chroma-data to locateLocal directory: CHROMA_DATA_PATH=./data
Custom path: CHROMA_DATA_PATH=/path/to/data
After changing CHROMA_DATA_PATH, restart the services:
docker compose restart
Method 1: Custom Connector (Recommended - Pro/Team/Enterprise)
ChromaDBhttps://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:
~/Library/Application Support/Claude/claude_desktop_config.json%APPDATA%\Claude\claude_desktop_config.jsonAdd 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.jsonusingstreamableHttptransport. You must either use Custom Connectors or themcp-remotewrapper package.
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
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.
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 collectionchroma_get_collection_info - Get collection metadatachroma_get_collection_count - Get document count (read_level optional)chroma_count_collections - Total collection count (v2.2.0)chroma_peek_collection - Preview collection contentschroma_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 filterchroma_heartbeat - Server heartbeat (nanosecond timestamp)chroma_get_server_version - Server version stringchroma_get_max_batch_size - Max batch size (for client-side splitting)chroma_get_user_identity - Current tenant + databasesCHROMA_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).CHROMA_ADMIN_TOOLS_ENABLED=true)chroma_admin_create_database / chroma_admin_get_database / chroma_admin_list_databaseschroma_admin_create_tenant / chroma_admin_get_tenantCHROMA_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)The MCP server proxies all ChromaDB REST API endpoints, allowing direct access from Python clients.
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"
)
)
Visit https://your-server.com/docs for Swagger UI documentation of all ChromaDB REST API endpoints.
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.
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:
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_TOKENin your environment.
Disable Funnel:
tailscale funnel 8080 off
# 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
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;
}
}
This project follows strict security practices and has resolved all security issues identified by static analysis:
For detailed security information, see Security Policy.
Enable Authentication for Public Access
MCP_AUTH_TOKEN when using Tailscale Funnel or public internetopenssl rand -base64 32 | tr '+/' '-_' | tr -d '='Use HTTPS
Prefer VPN Over Public Internet
Monitor Access
# Check for unauthorized access attempts
docker compose logs mcp-server | grep "Unauthorized"
Network Isolation
# 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
# 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
# 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
# Check logs
docker compose logs mcp-server
# Check port conflicts
lsof -i :3000
# Restart services
docker compose restart
/mcp pathstreamableHttp (not sse)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.
# 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}'
# 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
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:
Authorization: Bearer MCP_AUTH_TOKEN; OAuth 2.1 / OIDC multi-provider)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:
See __tests__/README.md for detailed testing strategy.
This project uses Codecov for code coverage tracking and test analytics.
# 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
# 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 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
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
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
⚠️ Breaking changes — operators upgrading from v2.2.2 or earlier must read this section.
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.
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:
MCP_AUTH_TOKEN or configure OIDC.ALLOW_INSECURE_NO_AUTH=true to your .env.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:
validateOriginHeader) — Origin: evil.example → 403ALLOW_INSECURE_NO_AUTH does not bypass the proxy)configuration.embedding_function in POST/PUT/PATCH body → 400Migration: If you relied on direct /api/v2/* REST passthrough, set
CHROMA_REST_PROXY_ENABLED=true and ensure authentication is configured.
Contributions are welcome! Please feel free to submit issues and pull requests.
git checkout -b feature/amazing-feature)git commit -m 'Add amazing feature')git push origin feature/amazing-feature)If you encounter any issues or have questions, please open an issue.
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.
Verified locally on Korean RAG workloads (2026-05). Pick by priority:
Notes from the verification run:
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.RERANKER_API_BASE unset to disable reranking without code changes.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.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
OIDC_AUDIENCE.OIDC_PRESET=google (or OIDC_ISSUERS=... for custom IdPs) and OIDC_AUDIENCE=....Authorization: Bearer <token> to /mcp.WWW-Authenticate: Bearer error="...", resource_metadata="<base>/.well-known/oauth-protected-resource" per RFC 9728.MCP_AUTH_TOKEN remains valid alongside OAuth — recommended for non-interactive workloads.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.
Remote ChromaDB vector database MCP server with streamable HTTP transport
{ "mcpServers": { "io.github.meloncafe-chromadb-remote-mcp": { "url": "https://meloncafe.github.io/chromadb-remote-mcp/mcp", "headers": {} } }}Herramientas
Aún no hay lista de herramientas. Los servidores remotos la reciben tras la primera comprobación de estado.
Preguntas frecuentes
Copia en esta página la configuración http para Cursor, Claude Desktop, Claude Code o VS Code. Usa la instalación del publicador, no un proxy de PlugMCP.
El publicador indica estas variables de entorno: CHROMADB_MCP_URL, MCP_AUTH_TOKEN.
Se accede a ChromaDB Remote MCP Server por HTTP.
Última comprobación: 2026-11-09. Remote ChromaDB vector database MCP server with streamable HTTP transport