Materials Project MCP

Instructions

Find materials with a specific chemical formula.

Args:
    formula: Chemical formula to search for (e.g., "Fe2O3").
    max_records: Maximum number of records to return (default: 10).

Returns:
    List of materials matching the specified formula.

Implementation Reference

• src/materials_project_mcp/tools.py:122-167 (handler)

  The handler function implementing the 'find_materials_by_formula' tool. It calls the underlying API wrapper and simplifies the results for the tool response.

  def find_materials_by_formula(
      formula: str,
      max_records: int = 10
  ) -> List[Dict[str, Any]]:
      """
      Find materials with a specific chemical formula.
      
      Args:
          formula: Chemical formula to search for (e.g., "Fe2O3").
          max_records: Maximum number of records to return (default: 10).
      
      Returns:
          List of materials matching the specified formula.
      """
      properties = [
          "material_id", 
          "formula_pretty",
          "symmetry", 
          "formation_energy_per_atom",
          "band_gap",
          "density",
          "is_stable"
      ]
      
      materials = fetch_materials_by_formula(
          formula=formula,
          max_records=max_records,
          properties=properties
      )
      
      # Extract key properties for each material
      simplified_results = []
      for material in materials:
          simplified_material = {
              "material_id": material.get("material_id"),
              "formula": material.get("formula_pretty"),
              "band_gap": material.get("band_gap"),
              "formation_energy": material.get("formation_energy_per_atom"),
              "crystal_system": material.get("symmetry", {}).get("crystal_system"),
              "space_group": material.get("symmetry", {}).get("symbol"),
              "density": material.get("density"),
              "is_stable": material.get("is_stable", False)
          }
          simplified_results.append(simplified_material)
      
      return simplified_results

• src/materials_project_mcp/main.py:22-22 (registration)

  Registers the 'find_materials_by_formula' tool with the FastMCP instance.

  mcp.tool(find_materials_by_formula)

• src/materials_project_mcp/api.py:132-170 (helper)

  Underlying API helper function that performs the actual Materials Project API search for materials by formula.

  def fetch_materials_by_formula(
      formula: str,
      max_records: int = 10,
      properties: Optional[List[str]] = None,
  ) -> List[Dict[str, Any]]:
      """
      Fetch materials matching a specific formula from the Materials Project API.
      
      Args:
          formula: Chemical formula to search for (e.g., "Fe2O3").
          max_records: Maximum number of records to return (default: 10).
          properties: Optional list of properties to include in the results.
      
      Returns:
          List of materials data dictionaries.
      """
      if properties is None:
          properties = [
              "material_id", 
              "formula_pretty",
              "symmetry", 
              "formation_energy_per_atom",
              "band_gap",
              "theoretical",
              "density",
              "is_stable"
          ]
      
      with get_mp_client() as mpr:
          # Search by formula
          results = mpr.materials.summary.search(
              formula=formula,
              fields=properties
          )
          
          # Limit the number of results and convert to dictionaries
          materials = [doc.dict() for doc in results[:max_records]]
          
      return materials