Chroma MCP Server

Instructions

Args:
    collection_name: Name of the collection to query
    query_texts: List of query texts to search for
    n_results: Number of results to return per query
    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, metadatas, and distances.

Implementation Reference

• src/chroma_mcp/server.py:395-441 (handler)

  The main handler function for the 'chroma_query_documents' tool. Decorated with @mcp.tool(), which handles both registration and schema definition (from type hints and docstring). Implements querying Chroma collection using query_texts with optional filters and includes.

  @mcp.tool()
  async def chroma_query_documents(
      collection_name: str,
      query_texts: List[str],
      n_results: int = 5,
      where: Dict | None = None,
      where_document: Dict | None = None,
      include: List[str] = ["documents", "metadatas", "distances"]
  ) -> Dict:
      """Query documents from a Chroma collection with advanced filtering.
      
      Args:
          collection_name: Name of the collection to query
          query_texts: List of query texts to search for
          n_results: Number of results to return per query
          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, metadatas, and distances.
      """
      if not query_texts:
          raise ValueError("The 'query_texts' list cannot be empty.")
  
      client = get_chroma_client()
      try:
          collection = client.get_collection(collection_name)
          return collection.query(
              query_texts=query_texts,
              n_results=n_results,
              where=where,
              where_document=where_document,
              include=include
          )
      except Exception as e:
          raise Exception(f"Failed to query documents from collection '{collection_name}': {str(e)}") from e

• src/chroma_mcp/server.py:395-441 (registration)

  The @mcp.tool() decorator registers the function as an MCP tool.

  @mcp.tool()
  async def chroma_query_documents(
      collection_name: str,
      query_texts: List[str],
      n_results: int = 5,
      where: Dict | None = None,
      where_document: Dict | None = None,
      include: List[str] = ["documents", "metadatas", "distances"]
  ) -> Dict:
      """Query documents from a Chroma collection with advanced filtering.
      
      Args:
          collection_name: Name of the collection to query
          query_texts: List of query texts to search for
          n_results: Number of results to return per query
          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, metadatas, and distances.
      """
      if not query_texts:
          raise ValueError("The 'query_texts' list cannot be empty.")
  
      client = get_chroma_client()
      try:
          collection = client.get_collection(collection_name)
          return collection.query(
              query_texts=query_texts,
              n_results=n_results,
              where=where,
              where_document=where_document,
              include=include
          )
      except Exception as e:
          raise Exception(f"Failed to query documents from collection '{collection_name}': {str(e)}") from e