go-chromadb-mcp-server by kevensen - MCP Server

go-chromadb-mcp-server

A Model Context Protocol (MCP) server implementation in Go for interacting with ChromaDB. This server enables AI assistants and other MCP clients to perform vector database operations and RAG (Retrieval-Augmented Generation) workflows using ChromaDB.

Features

Collection Management: Create, list, get, delete, and count collections
Document Operations: Add, update, upsert, get, delete, and count documents
Vector Search: Query collections for similar documents using embeddings
RAG Support: Full support for retrieval-augmented generation workflows
Multi-tenancy: Support for tenants and databases
Flexible Transport: Supports both stdio and HTTP transport modes

Requirements

Go 1.24 or later
ChromaDB server (running locally or remotely)

Installation

# Clone the repository
git clone https://github.com/kevensen/go-chromadb-mcp-server.git
cd go-chromadb-mcp-server

# Build the server
go build -o chromadb-mcp-server .

Usage

Basic Usage (stdio transport)

# Start the server with default ChromaDB connection
./chromadb-mcp-server

# Specify custom ChromaDB URL
./chromadb-mcp-server --chroma-url http://chromadb-server:8000

HTTP Transport

# Start server with HTTP transport on port 8080
./chromadb-mcp-server --transport http

Environment Variables

CHROMA_URL: ChromaDB server URL (default: http://localhost:8000)

Available Tools

Collection Management

`list_collections`

List all collections in ChromaDB.

Parameters:

tenant (optional): Tenant name
database (optional): Database name

`create_collection`

Create a new collection.

Parameters:

name (required): Collection name
metadata (optional): Collection metadata object
get_or_create (optional): Return existing collection if it exists
tenant (optional): Tenant name
database (optional): Database name

`get_collection`

Get a collection by name.

Parameters:

name (required): Collection name
tenant (optional): Tenant name
database (optional): Database name

`delete_collection`

Delete a collection by name.

Parameters:

name (required): Collection name
tenant (optional): Tenant name
database (optional): Database name

`count_collections`

Get the total number of collections.

Parameters:

tenant (optional): Tenant name
database (optional): Database name

Document Operations

`add_documents`

Add documents to a collection.

Parameters:

collection_id (required): Collection ID
ids (required): Array of document IDs
documents (optional): Array of document texts
embeddings (optional): Array of embeddings (can use ChromaDB's embedding function instead)
metadatas (optional): Array of metadata objects
tenant (optional): Tenant name
database (optional): Database name

`update_documents`

Update existing documents in a collection.

Parameters:

collection_id (required): Collection ID
ids (required): Array of document IDs to update
documents (optional): Array of updated document texts
embeddings (optional): Array of updated embeddings
metadatas (optional): Array of updated metadata objects
tenant (optional): Tenant name
database (optional): Database name

`upsert_documents`

Insert or update documents in a collection.

Parameters:

collection_id (required): Collection ID
ids (required): Array of document IDs
documents (optional): Array of document texts
embeddings (optional): Array of embeddings
metadatas (optional): Array of metadata objects
tenant (optional): Tenant name
database (optional): Database name

`get_documents`

Get documents from a collection.

Parameters:

collection_id (required): Collection ID
ids (optional): Specific document IDs to retrieve
where (optional): Metadata filter conditions
where_document (optional): Document content filter conditions
limit (optional): Maximum number of documents to return
offset (optional): Number of documents to skip
include (optional): Fields to include (documents, embeddings, metadatas)
tenant (optional): Tenant name
database (optional): Database name

`delete_documents`

Delete documents from a collection.

Parameters:

collection_id (required): Collection ID
ids (optional): Document IDs to delete
where (optional): Metadata filter for documents to delete
where_document (optional): Document content filter for documents to delete
tenant (optional): Tenant name
database (optional): Database name

`count_documents`

Count documents in a collection.

Parameters:

collection_id (required): Collection ID
tenant (optional): Tenant name
database (optional): Database name

Query and RAG

`query_collection`

Query a collection for similar documents using vector search.

Parameters:

collection_id (required): Collection ID
query_embeddings (required): Query embeddings for similarity search
n_results (optional): Number of results to return (default: 10)
where (optional): Metadata filter conditions
where_document (optional): Document content filter conditions
include (optional): Fields to include (documents, embeddings, metadatas, distances)
tenant (optional): Tenant name
database (optional): Database name

Utility

`heartbeat`

Check if ChromaDB server is alive.

`version`

Get ChromaDB server version.

Architecture

This MCP server follows idiomatic Go principles:

High Cohesion: Each component has a single, well-defined responsibility
Loose Coupling: Minimal dependencies between components
Table-Driven Tests: Comprehensive test coverage using Go's table-driven testing pattern
Clean Code: Clear separation between server setup, tool registration, and handler implementation

Project Structure

.
├── main.go           # Entry point and server initialization
├── server.go         # MCP server implementation and tool handlers
├── server_test.go    # Table-driven unit tests
├── go.mod            # Go module definition
└── README.md         # This file

Development

Running Tests

go test -v ./...

Building

go build -o chromadb-mcp-server .

Linting

go vet ./...
gofmt -s -w .

Dependencies

mcp-go: MCP framework for Go
go-chroma-client: ChromaDB client for Go

License

See file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.