Chromadb Remote Mcp

ChromaDB Remote MCP Server

[](https://modelcontextprotocol.io) [](https://www.typescriptlang.org/) [](LICENSE) [](https://mseep.ai/app/meloncafe-chromadb-remote-mcp) [](https://codecov.io/gh/meloncafe/chromadb-remote-mcp) [](https://app.deepsource.com/gh/meloncafe/chromadb-remote-mcp/)

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.

[한국어 문서](README.ko.md)

---

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

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 exist

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: meloncafe
• Source: meloncafe/chromadb-remote-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.