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 documentInput 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: