ChromaDB Remote MCP Server

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]