chromadb-remote

The Chromadb Remote MCP Server provides a streamable HTTP MCP interface that lets Claude and other MCP-compatible clients access a self-hosted ChromaDB instance remotely. It exposes an MCP Endpoint at /mcp for protocol-level requests, a REST API proxy at /api/v2/* for Python/JavaScript clients, and a Swagger/OpenAPI surface at /docs with an OpenAPI spec at /openapi.json. The system is designed to keep vector data private on your infrastructure while enabling seamless cross-device memory continuity across Claude Desktop, Claude Mobile, and Claude Code. Authentication is centralized via a single MCP token that also guards the REST API endpoints. To connect, configure your MCP client to point at http(s)://<your-host>/mcp and supply the authentication token from your .env or deployment configuration.

Clients and capabilities include: remote access to a shared ChromaDB instance, universal memory across devices, and full ChromaDB CRUD operations through the MCP streamable protocol. The REST API proxy allows Python and JavaScript clients to perform ChromaDB operations without directly interacting with the MCP layer. The server can be deployed with one-command Docker installation or via building from source for development workflows. The architecture ensures data persistence and synchronization across all connected clients.

Prerequisites:

• Docker and Docker Compose installed on the host
• Git installed to clone or fetch repository contents
• curl available for download/install scripts (optional)
• Basic familiarity with environment variable configuration (.env)

Recommended (One-Command Installation):

1. Run the one-command installer from the project to automatically fetch Docker assets and set up the environment.
   • Command: curl -fsSL https://raw.githubusercontent.com/meloncafe/chromadb-remote-mcp/release/scripts/install.sh | bash
   • This script will: download docker-compose.yml and .env.example, auto-detect docker compose syntax, optionally generate an auth token, configure storage for ChromaDB, pull images, and display the connection URL and token.

Manual Installation (Docker, Recommended):

1. Create a working directory and fetch 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
2. Configure environment
   • cp .env.example .env
   • Edit .env to set MCP_AUTH_TOKEN (generate a secure token), PORT (default 8080), and CHROMA_DATA_PATH (default chroma-data)
3. Start services
   • docker compose up -d
   • or: docker-compose up -d (for older Docker versions)
4. Verify health
   • curl http://localhost:8080/health
5. View logs (optional)
   • docker compose logs -f

Local Development (optional):

1. Clone the repository and install dependencies if you plan to build from source
   • git clone https://github.com/meloncafe/chromadb-remote-mcp.git
   • cd chromadb-remote-mcp
   • yarn install
2. Configure environment (.env) and build/run locally using Docker or Node environment as needed.

Generating a Secure Token: Use one of the recommended methods to generate a token and place it in .env:

• Node.js: node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
• OpenSSL: openssl rand -base64 32 | tr '+/' '-_' | tr -d '='

Environment variables and configuration tips:

• MCP_AUTH_TOKEN: A secure token used to authenticate MCP and REST API endpoints. Generate a strong token and store it in .env.
• PORT: Public port exposed by the load balancer or proxy (default 8080).
• CHROMA_DATA_PATH: Path or Docker volume where ChromaDB data is stored (default chroma-data).
• If using Docker Compose, ensure your host firewall allows access to the configured PORT.
• The Quick Start Docker deployment uses docker-compose to orchestrate multiple services (MCP server, REST proxy, and ChromaDB container). The MCP API is streamable HTTP, with SSE transport deprecated per the project notes.
• OpenAPI spec is available at /openapi.json and Swagger UI at /docs after the server is running.
• If you run into token-related authentication issues, ensure the MCP_AUTH_TOKEN in .env matches the token used by your MCP client configuration.
• For development builds, you can build from source and run locally, but the recommended deployment for production is the Docker-based one-command install due to easier maintenance and upgrades.