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