Chroma Memory MCP

An MCP server that gives Claude (and any MCP client) a shared team knowledge base with semantic search. Backed by ChromaDB and Google Gemini embeddings — works across languages (RU + EN).

How It Works

The server stores team knowledge as entries in ChromaDB. Each entry has a project, slug, title, content (Markdown), tags, type, and author. When someone asks a question, Claude runs a semantic search and answers with full context. When someone makes a decision worth sharing, they tell Claude to save it — and it's available to every team member.

Claude ──MCP──▶ chroma-memory-mcp ──▶ ChromaDB
                      │
                      ▼
              Gemini Embeddings
              (multilingual RU+EN)

Related MCP server: mcp-context

Quick Start

1. Start the server

git clone https://github.com/sfrangulov/chroma-memory-mcp
cd chroma-memory-mcp
export GOOGLE_API_KEY=your-gemini-api-key
docker compose up -d

The server is now available at http://localhost:3000/mcp.

2. Connect Claude Code

Add .mcp.json to your project root:

{
  "mcpServers": {
    "chroma-memory": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

3. Connect Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "chroma-memory": {
      "type": "http",
      "url": "http://localhost:3000/mcp"
    }
  }
}

MCP Tools

Entry types

• note (default) — general knowledge

• decision — architectural or process decisions

• snippet — reusable code fragments

• doc — documentation and reference material

• log — event logs and session records

Entry ID format

{project}:{slug} — for example mobile-app:auth-decision.

Configuration

*OAuth is optional. Without it, the server runs in dev mode (no auth). Without GOOGLE_API_KEY, semantic search is disabled (CRUD still works).

Deployment

Local (Docker Compose)

export GOOGLE_API_KEY=your-gemini-api-key
docker compose up -d

This starts ChromaDB + Redis + MCP server. Data persists in Docker volumes.

Production (Docker Compose + OAuth)

export GOOGLE_API_KEY=your-gemini-api-key
export GOOGLE_CLIENT_ID=your-client-id
export GOOGLE_CLIENT_SECRET=your-client-secret
export MCP_BASE_URL=https://memory.example.com
docker compose up -d

With OAuth enabled, each user authenticates via Google — their email becomes the author field on entries.

Kubernetes (Helm)

A Helm chart is included in helm/chroma-memory-mcp/. It deploys:

• MCP server (Node.js) — Deployment + Service

• ChromaDB — Deployment + PVC + Service

• Ingress with TLS (cert-manager + Let's Encrypt)

• Secrets for API keys

Prerequisites

• Kubernetes cluster with nginx ingress controller

• cert-manager with a ClusterIssuer (for TLS)

• DNS record pointing your domain to the cluster

Install

helm install chroma-memory ./helm/chroma-memory-mcp \
  --set secrets.googleApiKey=YOUR_GEMINI_API_KEY \
  --set secrets.googleClientId=YOUR_GOOGLE_CLIENT_ID \
  --set secrets.googleClientSecret=YOUR_GOOGLE_CLIENT_SECRET \
  --set ingress.host=memory.example.com

Key Helm values

# Namespace for all resources
namespace: chroma-memory

# MCP server
mcp:
  image:
    repository: sfrangulov/chroma-memory-mcp
    tag: "0.1.2"
  replicas: 1
  port: 3000

# ChromaDB
chromadb:
  image:
    repository: chromadb/chroma
    tag: "1.5.2"
  persistence:
    size: 5Gi
    storageClass: microk8s-hostpath

# Ingress
ingress:
  enabled: true
  className: public
  host: memory.example.com
  tls:
    enabled: true
    clusterIssuer: lets-encrypt

Upgrade

# Build new Docker image
docker build --platform linux/amd64 -t sfrangulov/chroma-memory-mcp:0.x.x .
docker push sfrangulov/chroma-memory-mcp:0.x.x

# Update Helm release
helm upgrade chroma-memory ./helm/chroma-memory-mcp \
  --set mcp.image.tag=0.x.x \
  --reuse-values

Nginx ingress notes

The Helm chart configures nginx annotations for MCP streaming:

• proxy-buffering: off — required for Streamable HTTP transport

• proxy-read-timeout: 3600 — long-lived connections

• proxy-body-size: 16m — large entries

Building the Docker image

# For local use
docker build -t chroma-memory-mcp .

# For Kubernetes (must be linux/amd64)
docker build --platform linux/amd64 -t sfrangulov/chroma-memory-mcp:0.x.x .
docker push sfrangulov/chroma-memory-mcp:0.x.x

Authentication

For production deployments, enable Google OAuth2:

1. Go to Google Cloud Console → APIs & Services → Credentials

2. Create an OAuth 2.0 Client ID (Web application type)

3. Add authorized redirect URI: https://your-domain.com/oauth/google/callback

4. Enable the Generative Language API (for Gemini embeddings)

5. Create an API Key (restrict to Generative Language API)

6. Set MCP_BASE_URL, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_API_KEY

The server automatically exposes OAuth discovery endpoints:

• /.well-known/oauth-authorization-server

• /.well-known/oauth-protected-resource

Without OAuth (dev mode), the server accepts all requests and sets author to anonymous.

OAuth Flow Details

• Tokens are opaque UUIDs issued by this server (not Google JWTs)

• Token TTL: 24 hours — users re-authenticate daily

• Refresh tokens are not supported — sessions expire after 24h

• Google ID tokens are cryptographically verified via JWKS

• Server restart invalidates all sessions (unless Redis is configured)

HTTP Endpoints

Usage Examples

Save a decision

"Remember for the team: we chose PostgreSQL over MongoDB for ACID compliance."

Claude calls write_entry with project, slug, title, content, and tags.

Search memory

"What did we decide about authentication?"

Claude calls search with the query, reviews results, and answers with context.

Browse a project

"What's in our project memory?"

Claude calls list_projects, then list_entries for the relevant project.

Tech Stack

Project Structure

├── server.js                 # MCP server + Express app
├── lib/
│   ├── memory-store.js       # ChromaDB wrapper (CRUD + search)
│   ├── auth.js               # Email extraction from auth info
│   ├── oauth-provider.js     # Google OAuth2 provider
│   └── session-store.js      # TTL session store (Memory/Redis)
├── test/                     # Unit + integration tests (Vitest)
├── Dockerfile                # Production image (node:20-slim)
├── docker-compose.yml        # Local development
├── docker-compose.test.yml   # Integration test environment
├── helm/                     # Kubernetes Helm chart
│   └── chroma-memory-mcp/
│       ├── Chart.yaml
│       ├── values.yaml
│       └── templates/
└── SKILL.md                  # Claude skill for using the MCP tools

Development

npm install

# Run unit tests
npm test

# Run integration tests (requires Docker)
docker compose -f docker-compose.test.yml up -d --wait
npm run test:integration
docker compose -f docker-compose.test.yml down

Set TEST_CHROMA_URL to override the default http://localhost:8100 for integration tests.

License

MIT