devsaurus/chromadb-remote-mcp

By devsaurus

•Updated 18 days ago

Remote ChromaDB MCP server for Claude Desktop/Mobile/Code with authentication and REST API proxy.

Image

API management

Developer tools

Web servers

7.0K

Overview Tags

devsaurus/chromadb-remote-mcp repository overview

⁠ChromaDB Remote MCP Server

Remote MCP (Model Context Protocol) server that provides secure access to ChromaDB for AI assistants like Claude. Enables semantic search and vector database operations from mobile devices and remote locations.

⁠Key Features

Remote Access: Connect from anywhere via Streamable HTTP transport
Cross-Platform: Works with Claude Desktop, Mobile, and Code
Shared Memory: All Claude clients use the same ChromaDB instance
Unified Authentication: Single token protects both MCP and REST API endpoints
REST API Proxy: Direct ChromaDB access for Python/JavaScript clients
Security: Rate limiting, security headers, DNS rebinding protection
Multi-Platform: Docker images for linux/amd64 and linux/arm64

⁠Quick Start

⁠Using Installation Script (Recommended)

One-command automated installation:

curl -fsSL https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/scripts/install.sh | bash

The script will:

Download docker-compose.yml and .env.example
Auto-generate secure authentication token
Configure ChromaDB data storage location
Pull Docker images
Display connection URL and token

After installation:

cd chromadb-remote-mcp
docker compose up -d

Update:

docker compose pull
docker compose down
docker compose up -d

⁠Manual Installation

# 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)

# Start services
docker compose up -d

# Check health
curl http://localhost:8080/health

⁠Generate Secure Token

# 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 '='

⁠Configuration

Configure via environment variables in .env file:

Variable	Description	Default
`PORT`	External port (Caddy proxy)	`8080`
`MCP_AUTH_TOKEN`	Authentication token (required for public access)	-
`CHROMA_DATA_PATH`	ChromaDB data storage path (volume name, ./data, or absolute path)	`chroma-data`
`CHROMA_HOST`	ChromaDB host (internal)	`chromadb`
`CHROMA_PORT`	ChromaDB port (internal)	`8000`
`CHROMA_TENANT`	ChromaDB tenant	`default_tenant`
`CHROMA_DATABASE`	ChromaDB database	`default_database`
`CHROMA_AUTH_TOKEN`	ChromaDB auth token (if ChromaDB requires auth)	-
`RATE_LIMIT_MAX`	Max requests per IP per 15 minutes	`100`
`ALLOWED_ORIGINS`	Comma-separated allowed origins (DNS rebinding protection)	-
`ALLOW_QUERY_AUTH`	Enable authentication via query parameters	`true`

⁠Authentication

IMPORTANT: For public internet access, you must set MCP_AUTH_TOKEN.

Supported authentication methods:

Authorization Header (Most Secure): Authorization: Bearer TOKEN
- Recommended for API clients
- Compliant with MCP specification
X-Chroma-Token Header: X-Chroma-Token: TOKEN
- For ChromaDB Python/JavaScript libraries
- Compatible with ChromaDB client SDKs
Query Parameter (Default Enabled): ?apiKey=TOKEN
- Required for Claude Desktop Custom Connector
- Enabled by default (ALLOW_QUERY_AUTH=true)
- Set ALLOW_QUERY_AUTH=false to disable

⁠Data Storage

ChromaDB data can be stored in three ways:

Docker volume (default): CHROMA_DATA_PATH=chroma-data
- Managed by Docker, survives container restarts
Local directory: CHROMA_DATA_PATH=./data
- Easy to backup and access
Custom path: CHROMA_DATA_PATH=/path/to/data
- Must be an absolute path

⁠Client Configuration

⁠Claude Desktop + Mobile

Method 1: Custom Connector (Recommended - Pro/Team/Enterprise)

Open Claude Desktop → Settings → Integrations → Custom Connector
Click "Add Custom Server"
Enter:
- Name: ChromaDB
- URL: https://your-server.com/mcp?apiKey=YOUR_TOKEN

Note: Custom connector automatically syncs to the mobile app.

Method 2: mcp-remote Wrapper (Free/Pro Users)

Configuration file location:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Add to configuration:

{
  "mcpServers": {
    "chromadb": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://your-server.com/mcp?apiKey=YOUR_TOKEN"]
    }
  }
}

⁠Claude Code

# With authentication (Query Parameter - Recommended)
claude mcp add --transport http chromadb https://your-server.com/mcp?apiKey=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

⁠Python/JavaScript (ChromaDB Client)

import chromadb

# HTTPS (Tailscale Funnel, public deployment)
client = chromadb.HttpClient(
    host="your-server.com",
    port=443,
    ssl=True,
    headers={
        "X-Chroma-Token": "YOUR_TOKEN"
    }
)

# Local development (HTTP)
client = chromadb.HttpClient(
    host="localhost",
    port=8080,
    ssl=False,
    headers={
        "X-Chroma-Token": "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)

⁠Available Endpoints

/mcp - MCP Protocol endpoint
/api/v2/* - ChromaDB REST API proxy
/health - Health check (no auth required)
/docs - Swagger UI documentation
/openapi.json - OpenAPI specification

⁠Security Features

Unified authentication with three methods (Bearer, X-Chroma-Token, query parameter)
Rate limiting per IP address (configurable)
Strict Content Security Policy (CSP)
Security headers (HSTS, X-Frame-Options, X-Content-Type-Options)
DNS rebinding attack prevention
Timing-safe token comparison
Log injection prevention

⁠MCP Tools

⁠Collection Management

chroma_list_collections - List all collections
chroma_create_collection - Create new collection
chroma_delete_collection - Delete collection
chroma_get_collection_info - Get collection metadata
chroma_get_collection_count - Get document count
chroma_peek_collection - Preview collection items

⁠Document Operations

chroma_add_documents - Add documents with embeddings
chroma_query_documents - Semantic search
chroma_get_documents - Retrieve by ID
chroma_update_documents - Update documents
chroma_delete_documents - Delete documents

⁠Architecture

Claude Desktop/Mobile/Code
         ↓
    MCP Server (this image)
    ├─ Authentication Gateway
    ├─ MCP Protocol Handler
    └─ REST API Proxy
         ↓
    ChromaDB (vector database)

⁠Production Deployment

⁠With Reverse Proxy (Caddy)

services:
  mcp-server:
    image: devsaurus/chromadb-remote-mcp:latest
    environment:
      - MCP_AUTH_TOKEN=${MCP_AUTH_TOKEN}
      - CHROMA_HOST=chromadb
    depends_on:
      - chromadb
    networks:
      - internal

  caddy:
    image: caddy:2-alpine
    ports:
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
    networks:
      - internal

  chromadb:
    image: chromadb/chroma:latest
    volumes:
      - chroma-data:/chroma/chroma
    networks:
      - internal

networks:
  internal:

volumes:
  chroma-data:

⁠With Tailscale

VPN-only access:

# 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

Public internet access:

# 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: Public internet access requires MCP_AUTH_TOKEN to be set.

⁠With Nginx

server {
    listen 80;
    server_name your-domain.com;

    location / {
        proxy_pass http://localhost:8080;
        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;
    }
}

⁠Health Check

The container includes a built-in health check:

# Check service health
curl http://localhost:8080/health

# Docker health status
docker inspect --format='{{.State.Health.Status}}' mcp-server

⁠Testing

# Health check
curl http://localhost:8080/health

# MCP tools list
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# ChromaDB heartbeat
curl http://localhost:8080/api/v2/heartbeat

⁠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 (Query parameter)
curl -X POST "https://your-server.com/mcp?apiKey=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 "X-Chroma-Token: YOUR_TOKEN"

⁠Volumes

Container exposes port 3000 (internal)
External access via Caddy proxy on port 8080 (configurable via PORT env var)
No persistent volumes required in MCP server container
ChromaDB requires volume for data persistence

⁠Links

GitHub: https://github.com/meloncafe/chromadb-remote-mcp⁠
Documentation: https://github.com/meloncafe/chromadb-remote-mcp#readme⁠
Issues: https://github.com/meloncafe/chromadb-remote-mcp/issues⁠
Security Policy: https://github.com/meloncafe/chromadb-remote-mcp/blob/release/SECURITY.md⁠

⁠License

MIT License - see LICENSE⁠ for details.

⁠Support

Documentation: README.md⁠
Issues: GitHub Issues⁠

Tag summary

Recent tags

Content type

Image

Digest

sha256:9d4e3a5e0…

Size

774.7 MB

Last updated

18 days ago

docker pull devsaurus/chromadb-remote-mcp