MCP Materials Server

Instructions

Search for materials containing specific elements.

Args:
    elements: List of elements that must be present (e.g., ["Li", "Fe", "O"])
    exclude_elements: Optional list of elements to exclude
    max_results: Maximum number of results (default: 10)

Returns:
    JSON with matching materials

Implementation Reference

• src/mcp_materials/server.py:265-325 (handler)

  The core handler function for the 'search_by_elements' tool. Decorated with @mcp.tool() for automatic registration and schema generation from signature/docstring. Queries Materials Project API for materials matching element criteria and returns formatted JSON results.

  @mcp.tool()
  def search_by_elements(
      elements: list[str],
      exclude_elements: list[str] | None = None,
      max_results: int = 10,
  ) -> str:
      """
      Search for materials containing specific elements.
  
      Args:
          elements: List of elements that must be present (e.g., ["Li", "Fe", "O"])
          exclude_elements: Optional list of elements to exclude
          max_results: Maximum number of results (default: 10)
  
      Returns:
          JSON with matching materials
      """
      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(
                  elements=elements,
                  exclude_elements=exclude_elements or [],
                  fields=[
                      "material_id",
                      "formula_pretty",
                      "energy_above_hull",
                      "band_gap",
                      "is_stable",
                  ],
                  num_chunks=1,
                  chunk_size=max_results,
              )
  
              results = []
              for doc in docs[:max_results]:
                  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,
                      "is_stable": doc.is_stable,
                  })
  
              return json.dumps({
                  "query": {
                      "must_include": elements,
                      "must_exclude": exclude_elements,
                  },
                  "count": len(results),
                  "materials": results,
              }, indent=2)
  
      except Exception as e:
          return json.dumps({"error": str(e)})