Mat DB Mp

Materials Project Database Query

<!-- mcp-tools-note -->

[!NOTE] Steps written server.tool are MCP tool calls: base.search_materials_project_by_formula is the search_materials_project_by_formula tool of the base server (mcp__base__search_materials_project_by_formula, or mcp__plugin_atomistic-skills_base__search_materials_project_by_formula when installed as a plugin). Without a connected server, run the same tools from the shell. Tools named in one command share a process, so a model loaded by load_model stays loaded:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python -m src.mcp_server.cli base search_materials_project_by_formula key=value search_materials_project_by_chemsys key=value

Goal

To retrieve crystal structures and computed properties from the Materials Project database, enabling efficient materials discovery and property analysis. This skill provides access to:

• Basic material properties (energy above hull, formation energy, band gap)
• Elastic properties (bulk modulus, shear modulus, elastic tensors)
• Magnetic properties (magnetic ordering, magnetization, site moments)
• Structure similarity search (CrystalNN-based fingerprinting)

Note: For quick structure retrieval by formula or chemical system, MCP tools are also available (see MCP Tools section).

Instructions

1. Query Materials by Chemical System or Formula

Use query_mp.py to search for materials by chemical system, formula, or elements with property filtering.

Basic Query (Summary Endpoint):

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/query_mp.py \
    --chemsys "Li-S" \
    --properties energy_above_hull formation_energy_per_atom band_gap \
    --e_above_hull_max 0.05 \
    --limit 10 \
    --endpoint summary \
    --output stable_li_s_materials.json

Detailed Thermodynamic Data (Thermo Endpoint):

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/query_mp.py \
    --chemsys "Li-O" \
    --endpoint thermo \
    --limit 20 \
    --output li_o_thermo.json

Key Parameters:

• --chemsys: Chemical system (e.g., "Li-S", "Si-O")
• --formula: Specific chemical formula (e.g., "LiFePO4")
• --elements: List of elements that must be present
• --properties: Properties to retrieve (default: energy_above_hull, formation_energy_per_atom)
• --e_above_hull_max: Maximum energy above hull for stability filtering (eV/atom)
• --endpoint: Choose summary (includes structures) or thermo (detailed thermodynamics, no structures)
• --limit: Maximum number of results to retrieve

Output: JSON file containing material IDs, formulas, CIF strings (summary endpoint), and requested properties.

2. Query Elastic Properties

Use get_elasticity.py to retrieve bulk modulus, shear modulus, and elastic tensor data.

Query Specific Material:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/get_elasticity.py \
    --material_id mp-149 \
    --output si_elasticity.json

Filter by Bulk Modulus Range:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/get_elasticity.py \
    --bulk_modulus_min 200 \
    --bulk_modulus_max 400 \
    --output high_bulk_modulus.json

Key Parameters:

• --material_id: Specific MP ID(s) to query
• --bulk_modulus_min/max: Bulk modulus (VRH) range in GPa
• --shear_modulus_min/max: Shear modulus (VRH) range in GPa

Output: JSON file with bulk modulus, shear modulus (Voigt, Reuss, VRH averages), and full elastic tensor.

3. Query Magnetic Properties

Use get_magnetism.py to retrieve magnetic ordering, magnetization, and site-specific magnetic moments.

Query Specific Material:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/get_magnetism.py \
    --material_id mp-19770 \
    --output fe2o3_magnetism.json

Filter by Magnetic Ordering and Magnetization:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/get_magnetism.py \
    --ordering FM \
    --total_magnetization_min 10.0 \
    --output ferromagnetic_materials.json

Key Parameters:

• --material_id: Specific MP ID(s) to query
• --ordering: Magnetic ordering type (FM, AFM, FiM, NM)
• --total_magnetization_min/max: Total magnetization range in μB

Output: JSON file with magnetic ordering, total magnetization, and per-site magnetic moments.

4. Retrieve Structures by Material ID

Use get_structure_by_id.py to retrieve crystal structures directly by their Materials Project ID.

Single Structure Retrieval:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/get_structure_by_id.py mp-149 \
    --output Si_diamond.cif

Batch Retrieval:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/get_structure_by_id.py \
    mp-149 mp-19017 mp-1143 \
    --output_dir structures/

Key Parameters:

• material_ids: One or more MP IDs to retrieve
• --output: Output path for single material ID (CIF format)
• --output_dir: Output directory for batch retrieval
• --api_key: Optional API key (uses MP_API_KEY env var by default)

Output: CIF file(s) containing the crystal structure(s).

5. Find Structurally Similar Materials

Use find_similar_structures.py to find materials with similar crystal structures based on CrystalNN fingerprinting.

Find Similar to MP Material:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/find_similar_structures.py \
    --material_id mp-149 \
    --top 15 \
    --output similar_to_si.json

Find Similar to Custom Structure:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/find_similar_structures.py \
    --structure my_structure.cif \
    --top 20 \
    --output similar_structures.json

Filter by Chemical System:

${CLAUDE_SKILL_DIR}/../../venv/run cpu python ${CLAUDE_SKILL_DIR}/scripts/find_similar_structures.py \
    --material_id mp-149 \
    --top 20 \
    --chemsys "C" \
    --output carbon_structures_like_si.json

Key Parameters:

• --material_id: MP ID to use as query structure
• --structure: Path to custom structure file (CIF, POSCAR, etc.)
• --top: Number of most similar structures to return (default: 50)
• --chemsys: Optional post-filter by exact chemical system match

Similarity Algorithm: Uses CrystalNN to compute local coordination fingerprints, aggregates them into structure fingerprints, and ranks by Euclidean distance in fingerprint space. Dissimilarity score: 100 * (1 - exp(-distance)), where 0% = identical and 100% = maximally different.

Output: JSON file with similar material IDs, formulas, and dissimilarity scores (0-100%).

Examples

See the examples/ directory for complete working examples:

Basic Queries (examples/query_mp/):

cd skills/mat-db-mp
bash examples/query_mp/li_s_stability.sh
# Output: Retrieves 2 stable Li-S materials (E_hull < 0.05 eV/atom)

Elastic Properties (examples/elasticity/):

cd skills/mat-db-mp
bash examples/elasticity/elasticity_query.sh
# Output: Si elastic data + 1387 materials with K=200-400 GPa

Magnetic Properties (examples/magnetism/):

cd skills/mat-db-mp
bash examples/magnetism/magnetism_query.sh
# Output: Fe2O3 magnetic data + 23,121 ferromagnetic materials

Structure Similarity (examples/similarity/):

cd skills/mat-db-mp
bash examples/similarity/similarity_search.sh
# Output: 15 structures similar to Si (mp-149)

Structure Retrieval (examples/get_structure/):

cd skills/mat-db-mp
bash examples/get_structure/structure_retrieval.sh
# Output: CIF files for Si, LiFePO4, and Fe2O3