chroma_add_documents

Enables adding text documents to a Chroma collection with optional metadata. Specify collection name, document IDs, and content for efficient data storage and retrieval.

Instructions

Add documents to a Chroma collection.

Args:
    collection_name: Name of the collection to add documents to
    documents: List of text documents to add
    ids: List of IDs for the documents (required)
    metadatas: Optional list of metadata dictionaries for each document

Input Schema

TableJSON Schema

Name	Required	Description	Default
`collection_name`	Yes
`documents`	Yes
`ids`	Yes
`metadatas`	No

Implementation Reference

src/chroma_mcp/server.py:332-393 (handler)

The chroma_add_documents tool handler. Decorated with @mcp.tool() for automatic registration in FastMCP. Implements document addition to ChromaDB collection with validation for empty inputs, ID uniqueness, and length matching. Uses get_chroma_client() helper and performs add operation.

@mcp.tool()
async def chroma_add_documents(
    collection_name: str,
    documents: List[str],
    ids: List[str],
    metadatas: List[Dict] | None = None
) -> str:
    """Add documents to a Chroma collection.
    
    Args:
        collection_name: Name of the collection to add documents to
        documents: List of text documents to add
        ids: List of IDs for the documents (required)
        metadatas: Optional list of metadata dictionaries for each document
    """
    if not documents:
        raise ValueError("The 'documents' list cannot be empty.")
    
    if not ids:
        raise ValueError("The 'ids' list is required and cannot be empty.")
    
    # Check if there are empty strings in the ids list
    if any(not id.strip() for id in ids):
        raise ValueError("IDs cannot be empty strings.")
    
    if len(ids) != len(documents):
        raise ValueError(f"Number of ids ({len(ids)}) must match number of documents ({len(documents)}).")

    client = get_chroma_client()
    try:
        collection = client.get_or_create_collection(collection_name)
        
        # Check for duplicate IDs
        existing_ids = collection.get(include=[])["ids"]
        duplicate_ids = [id for id in ids if id in existing_ids]
        
        if duplicate_ids:
            raise ValueError(
                f"The following IDs already exist in collection '{collection_name}': {duplicate_ids}. "
                f"Use 'chroma_update_documents' to update existing documents."
            )
        
        result = collection.add(
            documents=documents,
            metadatas=metadatas,
            ids=ids
        )
        
        # Check the return value
        if result and isinstance(result, dict):
            # If the return value is a dictionary, it may contain success information
            if 'success' in result and not result['success']:
                raise Exception(f"Failed to add documents: {result.get('error', 'Unknown error')}")
            
            # If the return value contains the actual number added
            if 'count' in result:
                return f"Successfully added {result['count']} documents to collection {collection_name}"
        
        # Default return
        return f"Successfully added {len(documents)} documents to collection {collection_name}, result is {result}"
    except Exception as e:
        raise Exception(f"Failed to add documents to collection '{collection_name}': {str(e)}") from e

src/chroma_mcp/server.py:332-332 (registration)
The @mcp.tool() decorator registers the chroma_add_documents function as an MCP tool.
```
@mcp.tool()
```
src/chroma_mcp/server.py:333-338 (schema)
Input schema defined by function type hints: collection_name (str), documents (List[str]), ids (List[str]), metadatas (optional List[Dict]). Returns str confirmation.
```
async def chroma_add_documents(
    collection_name: str,
    documents: List[str],
    ids: List[str],
    metadatas: List[Dict] | None = None
) -> str:
```

Chroma MCP Server