Chroma MCP Server

Instructions

Args:
    collection_name: Name of the collection to get documents from
    ids: Optional list of document IDs to retrieve
    where: Optional metadata filters using Chroma's query operators
           Examples:
           - Simple equality: {"metadata_field": "value"}
           - Comparison: {"metadata_field": {"$gt": 5}}
           - Logical AND: {"$and": [{"field1": {"$eq": "value1"}}, {"field2": {"$gt": 5}}]}
           - Logical OR: {"$or": [{"field1": {"$eq": "value1"}}, {"field1": {"$eq": "value2"}}]}
    where_document: Optional document content filters
           Examples:
           - Contains: {"$contains": "value"}
           - Not contains: {"$not_contains": "value"}
           - Regex: {"$regex": "[a-z]+"}
           - Not regex: {"$not_regex": "[a-z]+"}
           - Logical AND: {"$and": [{"$contains": "value1"}, {"$not_regex": "[a-z]+"}]}
           - Logical OR: {"$or": [{"$regex": "[a-z]+"}, {"$not_contains": "value2"}]}
    include: List of what to include in response. By default, this will include documents, and metadatas.
    limit: Optional maximum number of documents to return
    offset: Optional number of documents to skip before returning results

Returns:
    Dictionary containing the matching documents, their IDs, and requested includes

Implementation Reference

• src/chroma_mcp/server.py:442-490 (handler)

  The handler function for the 'chroma_get_documents' tool. It is decorated with @mcp.tool() for registration and implements the core logic: retrieves a Chroma collection and calls its .get() method with provided parameters (ids, where, where_document, include, limit, offset), returning the results or raising an exception on failure.

  @mcp.tool()
  async def chroma_get_documents(
      collection_name: str,
      ids: List[str] | None = None,
      where: Dict | None = None,
      where_document: Dict | None = None,
      include: List[str] = ["documents", "metadatas"],
      limit: int | None = None,
      offset: int | None = None
  ) -> Dict:
      """Get documents from a Chroma collection with optional filtering.
      
      Args:
          collection_name: Name of the collection to get documents from
          ids: Optional list of document IDs to retrieve
          where: Optional metadata filters using Chroma's query operators
                 Examples:
                 - Simple equality: {"metadata_field": "value"}
                 - Comparison: {"metadata_field": {"$gt": 5}}
                 - Logical AND: {"$and": [{"field1": {"$eq": "value1"}}, {"field2": {"$gt": 5}}]}
                 - Logical OR: {"$or": [{"field1": {"$eq": "value1"}}, {"field1": {"$eq": "value2"}}]}
          where_document: Optional document content filters
                 Examples:
                 - Contains: {"$contains": "value"}
                 - Not contains: {"$not_contains": "value"}
                 - Regex: {"$regex": "[a-z]+"}
                 - Not regex: {"$not_regex": "[a-z]+"}
                 - Logical AND: {"$and": [{"$contains": "value1"}, {"$not_regex": "[a-z]+"}]}
                 - Logical OR: {"$or": [{"$regex": "[a-z]+"}, {"$not_contains": "value2"}]}
          include: List of what to include in response. By default, this will include documents, and metadatas.
          limit: Optional maximum number of documents to return
          offset: Optional number of documents to skip before returning results
      
      Returns:
          Dictionary containing the matching documents, their IDs, and requested includes
      """
      client = get_chroma_client()
      try:
          collection = client.get_collection(collection_name)
          return collection.get(
              ids=ids,
              where=where,
              where_document=where_document,
              include=include,
              limit=limit,
              offset=offset
          )
      except Exception as e:
          raise Exception(f"Failed to get documents from collection '{collection_name}': {str(e)}") from e