MCP Materials Server

Instructions

Search for materials by band gap range.

Args:
    min_gap: Minimum band gap in eV (default: 0)
    max_gap: Maximum band gap in eV (default: 10)
    direct_gap_only: Only return materials with direct band gaps
    max_results: Maximum number of results (default: 10)

Returns:
    JSON with materials in the specified band gap range

Implementation Reference

• src/mcp_materials/server.py:327-396 (handler)

  The handler function for the 'search_by_band_gap' MCP tool. Decorated with @mcp.tool(), it queries the Materials Project database for materials within a specified band gap range (min_gap to max_gap), optionally filtering for direct band gaps only. Returns JSON with matching materials including material_id, formula, band_gap, stability, etc.

  @mcp.tool()
  def search_by_band_gap(
      min_gap: float = 0.0,
      max_gap: float = 10.0,
      direct_gap_only: bool = False,
      max_results: int = 10,
  ) -> str:
      """
      Search for materials by band gap range.
  
      Args:
          min_gap: Minimum band gap in eV (default: 0)
          max_gap: Maximum band gap in eV (default: 10)
          direct_gap_only: Only return materials with direct band gaps
          max_results: Maximum number of results (default: 10)
  
      Returns:
          JSON with materials in the specified band gap range
      """
      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:
              search_kwargs: dict[str, Any] = {
                  "band_gap": (min_gap, max_gap),
                  "fields": [
                      "material_id",
                      "formula_pretty",
                      "band_gap",
                      "is_gap_direct",
                      "energy_above_hull",
                      "is_stable",
                  ],
                  "num_chunks": 1,
                  "chunk_size": max_results * 2,  # Get extra in case we filter
              }
  
              if direct_gap_only:
                  search_kwargs["is_gap_direct"] = True
  
              docs = mpr.materials.summary.search(**search_kwargs)
  
              results = []
              for doc in docs:
                  if len(results) >= max_results:
                      break
                  results.append({
                      "material_id": str(doc.material_id),
                      "formula": doc.formula_pretty,
                      "band_gap_eV": doc.band_gap,
                      "is_direct_gap": doc.is_gap_direct,
                      "energy_above_hull_eV": doc.energy_above_hull,
                      "is_stable": doc.is_stable,
                  })
  
              return json.dumps({
                  "query": {
                      "band_gap_range_eV": [min_gap, max_gap],
                      "direct_gap_only": direct_gap_only,
                  },
                  "count": len(results),
                  "materials": results,
              }, indent=2)
  
      except Exception as e:
          return json.dumps({"error": str(e)})