search_materials

Instructions

Search for materials by chemical formula in the Materials Project database.

Args:
    formula: Chemical formula (e.g., "Fe2O3", "LiFePO4", "Si")
    max_results: Maximum number of results to return (default: 10)

Returns:
    JSON with matching materials including material_id, formula, and key properties

Implementation Reference

• src/mcp_materials/server.py:42-107 (handler)

  Full implementation of the 'search_materials' tool handler. Decorated with @mcp.tool() for automatic registration in the FastMCP server. Performs API key check, queries Materials Project via MPRester for materials matching the formula, extracts key properties (formula, energy above hull, band gap, etc.), formats as JSON.

  @mcp.tool()
  def search_materials(
      formula: str,
      max_results: int = 10,
  ) -> str:
      """
      Search for materials by chemical formula in the Materials Project database.
  
      Args:
          formula: Chemical formula (e.g., "Fe2O3", "LiFePO4", "Si")
          max_results: Maximum number of results to return (default: 10)
  
      Returns:
          JSON with matching materials including material_id, formula, and key properties
      """
      has_key, key_or_error = check_api_key()
      if not has_key:
          return json.dumps({"error": key_or_error})
  
      try:
          from mp_api.client import MPRester
  
          with MPRester(key_or_error) as mpr:
              docs = mpr.materials.summary.search(
                  formula=formula,
                  fields=[
                      "material_id",
                      "formula_pretty",
                      "energy_above_hull",
                      "band_gap",
                      "formation_energy_per_atom",
                      "density",
                      "symmetry",
                      "is_stable",
                  ],
                  num_chunks=1,
                  chunk_size=max_results,
              )
  
              results = []
              for doc in docs[:max_results]:
                  crystal_system = None
                  if doc.symmetry and doc.symmetry.crystal_system:
                      crystal_system = str(doc.symmetry.crystal_system.value) if hasattr(doc.symmetry.crystal_system, 'value') else str(doc.symmetry.crystal_system)
                  results.append({
                      "material_id": str(doc.material_id),
                      "formula": doc.formula_pretty,
                      "energy_above_hull_eV": doc.energy_above_hull,
                      "band_gap_eV": doc.band_gap,
                      "formation_energy_eV_atom": doc.formation_energy_per_atom,
                      "density_g_cm3": doc.density,
                      "crystal_system": crystal_system,
                      "space_group": doc.symmetry.symbol if doc.symmetry else None,
                      "is_stable": doc.is_stable,
                  })
  
              return json.dumps({
                  "count": len(results),
                  "materials": results,
              }, indent=2)
  
      except ImportError:
          return json.dumps({"error": "mp-api package not installed. Run: pip install mp-api"})
      except Exception as e:
          return json.dumps({"error": str(e)})

• src/mcp_materials/server.py:43-56 (schema)

  Input schema defined by function parameters with type hints: formula (str), max_results (int, default 10). Output: str (JSON). Detailed Arg/Return docstring provides validation guidance.

  def search_materials(
      formula: str,
      max_results: int = 10,
  ) -> str:
      """
      Search for materials by chemical formula in the Materials Project database.
  
      Args:
          formula: Chemical formula (e.g., "Fe2O3", "LiFePO4", "Si")
          max_results: Maximum number of results to return (default: 10)
  
      Returns:
          JSON with matching materials including material_id, formula, and key properties
      """

• src/mcp_materials/server.py:42-42 (registration)

  The @mcp.tool() decorator registers the search_materials function as an MCP tool on the FastMCP instance.

  @mcp.tool()

• src/mcp_materials/server.py:25-36 (helper)

  Helper functions for API key management: get_mp_api_key retrieves the key from env var, check_api_key validates it and returns error message if missing. Used by search_materials.

  def get_mp_api_key() -> str | None:
      """Get Materials Project API key from environment."""
      return os.environ.get("MP_API_KEY")
  
  
  def check_api_key() -> tuple[bool, str]:
      """Check if API key is configured."""
      key = get_mp_api_key()
      if not key:
          return False, "MP_API_KEY environment variable not set. Get your key at https://materialsproject.org/api"
      return True, key