search_materials
Search the Materials Project database for materials by chemical formula to retrieve material IDs, formulas, and key properties.
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
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| formula | Yes | ||
| max_results | No |
Implementation Reference
- src/mcp_materials/server.py:42-107 (handler)The core handler function for the 'search_materials' MCP tool. Decorated with @mcp.tool() for automatic registration and schema generation from signature/docstring. Performs API key check, queries Materials Project via mp_api for materials matching the formula, extracts key properties, and returns formatted 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:25-36 (helper)Helper functions get_mp_api_key() and check_api_key() used by search_materials for API key validation from environment.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
- src/mcp_materials/server.py:19-19 (registration)Initialization of FastMCP server instance where tools are registered via decorators. The server is run at line 831 with mcp.run() to expose all @mcp.tool() functions including search_materials.mcp = FastMCP("materials-science")
- src/mcp_materials/server.py:43-56 (schema)Input schema defined by type hints (formula: str, max_results: int=10) and output str (JSON). Docstring provides detailed descriptions used by MCP for tool schema.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 """