search_by_elements
Find materials containing specific elements while optionally excluding others to filter search results in materials science databases.
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 materialsInput Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| elements | Yes | ||
| exclude_elements | No | ||
| max_results | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |
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)})