Skip to main content
Glama
MCP Materials Server

MCP Materials Server

by HeshamFS

MCP Materials Server

A Model Context Protocol (MCP) server that provides AI assistants with access to materials science databases, starting with the Materials Project API.

Built with the MCP Python SDK using FastMCP.

Features

Tools (10)

Tool

Description

search_materials

Search materials by chemical formula (e.g., "Fe2O3", "LiFePO4")

get_structure

Retrieve crystal structure in CIF, POSCAR, or JSON format

get_properties

Get comprehensive material properties (band gap, formation energy, etc.)

compare_materials

Side-by-side comparison of multiple materials

search_by_elements

Find materials containing/excluding specific elements

search_by_band_gap

Search by electronic band gap range (eV)

get_similar_structures

Find materials with similar crystal structures

get_phase_diagram

Phase stability analysis for chemical systems

get_elastic_properties

Mechanical properties (bulk/shear modulus, Debye temperature)

search_by_elastic_properties

Find materials by mechanical property ranges

Resources (2)

Resource

URI

Description

Periodic Table

materials://periodic-table

Element data with atomic numbers and masses

Crystal Systems

materials://crystal-systems

The 7 crystal systems with symmetry constraints

Prompts (3)

Prompt

Description

analyze_material

Comprehensive analysis workflow for a material ID

find_battery_materials

Search for battery electrode candidates

compare_alloy_compositions

Compare phases in an alloy system

Related MCP server: Materials Project Platform MCP Server

Installation

Prerequisites

  • Python 3.11 or higher

  • Materials Project API key (get one free)

Setup

# Clone or navigate to the project
cd mcp-materials-server

# Create virtual environment
python -m venv .venv

# Activate virtual environment
# On Windows:
.venv\Scripts\activate
# On macOS/Linux:
source .venv/bin/activate

# Install the package
pip install -e ".[dev]"

Set API Key

# On Windows (PowerShell):
$env:MP_API_KEY = "your_api_key_here"

# On Windows (CMD):
set MP_API_KEY=your_api_key_here

# On macOS/Linux:
export MP_API_KEY="your_api_key_here"

Usage

Run the Server

# Using the installed command
mcp-materials

# Or run directly
python -m mcp_materials.server

Claude Desktop Integration

Add to your Claude Desktop configuration file:

Location:

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Configuration:

{
  "mcpServers": {
    "materials": {
      "command": "python",
      "args": ["-m", "mcp_materials.server"],
      "cwd": "D:\\path\\to\\mcp-materials-server",
      "env": {
        "MP_API_KEY": "your_api_key_here"
      }
    }
  }
}

After adding the configuration, restart Claude Desktop.

Example Queries

Once connected to Claude, you can ask:

Basic Searches

  • "Search for lithium cobalt oxide materials"

  • "Find materials with formula Fe2O3"

  • "Search for materials containing Li, Fe, and O"

Property Lookups

  • "Get the properties of mp-149 (Silicon)"

  • "What is the band gap of mp-19017?"

  • "Get the crystal structure of mp-149 in CIF format"

Advanced Analysis

  • "Find materials with band gap between 1.5 and 2.5 eV"

  • "Get the elastic properties of silicon (mp-149)"

  • "Generate a phase diagram for the Li-Fe-O system"

  • "Compare the properties of LiCoO2 and LiFePO4"

  • "Find stiff materials with bulk modulus > 200 GPa"

Research Workflows

  • "Analyze material mp-149 comprehensively"

  • "Find potential Li-ion battery cathode materials"

  • "Compare phases in the Fe-Cr-Ni alloy system"

Development

Run Tests

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test class
pytest tests/test_server.py::TestToolFunctions -v

Lint Code

# Check for issues
ruff check src/

# Auto-format
ruff format src/

Project Structure

mcp-materials-server/
├── src/
│   └── mcp_materials/
│       ├── __init__.py          # Package version
│       └── server.py            # MCP server (10 tools, 2 resources, 3 prompts)
├── tests/
│   ├── __init__.py
│   ├── conftest.py              # Pytest configuration
│   └── test_server.py           # Comprehensive test suite
├── pyproject.toml               # Project configuration
├── claude_desktop_config.example.json
├── .gitignore
└── README.md

API Reference

Tool Details

search_materials(formula, max_results=10)

Search by chemical formula. Returns material IDs, band gaps, formation energies, and stability.

get_structure(material_id, format="cif")

Get crystal structure. Formats: cif, poscar, json.

get_properties(material_id)

Full property set: composition, symmetry, electronic, thermodynamic properties.

compare_materials(material_ids)

Compare list of materials side-by-side.

search_by_elements(elements, exclude_elements=None, max_results=10)

Find materials by element composition.

search_by_band_gap(min_gap=0, max_gap=10, direct_gap_only=False, max_results=10)

Search by band gap range in eV.

get_similar_structures(material_id, max_results=5)

Find materials with same space group.

get_phase_diagram(elements)

Build phase diagram for chemical system. Returns stable/unstable phases with decomposition products.

get_elastic_properties(material_id)

Mechanical properties: bulk modulus, shear modulus (Voigt/Reuss/VRH), Poisson ratio, Debye temperature.

search_by_elastic_properties(min_bulk_modulus=None, max_bulk_modulus=None, min_shear_modulus=None, max_shear_modulus=None, max_results=10)

Filter materials by mechanical properties.

Roadmap

  • Add AFLOW database integration

  • Add OQMD database support

  • Add electronic structure (DOS, band structure) tools

  • Add XRD pattern simulation

  • Add synthesis route suggestions

  • Add surface/interface properties

License

MIT

References

Author

Hesham Salama

Available Tools

10 tools
compare_materialsB
Compare properties of multiple materials side by side.

Args:
    material_ids: List of Materials Project IDs (e.g., ["mp-149", "mp-66"])

Returns:
    JSON table comparing key properties across materials

Inputs: material_ids (required). Returns: result

get_elastic_propertiesB
Get elastic and mechanical properties for a material.

Args:
    material_id: Materials Project ID (e.g., "mp-149" for Silicon)

Returns:
    JSON with elastic properties including bulk modulus, shear modulus,
    Young's modulus, Poisson's ratio, and elastic tensor

Inputs: material_id (required). Returns: result

get_phase_diagramB
Get phase diagram data for a chemical system.

Args:
    elements: List of elements defining the system (e.g., ["Li", "Fe", "O"] for Li-Fe-O system)

Returns:
    JSON with phase diagram entries including stable phases, formation energies, and decomposition products

Inputs: elements (required). Returns: result

get_propertiesB
Get detailed properties for a specific material from Materials Project.

Args:
    material_id: Materials Project ID (e.g., "mp-149" for Silicon)

Returns:
    JSON with comprehensive material properties

Inputs: material_id (required). Returns: result

get_similar_structuresC
Find materials with similar crystal structures.

Args:
    material_id: Materials Project ID to find similar structures for
    max_results: Maximum number of similar structures (default: 5)

Returns:
    JSON with structurally similar materials

Inputs: material_id (required), max_results. Returns: result

get_structureA
Get the crystal structure for a material from Materials Project.

Args:
    material_id: Materials Project ID (e.g., "mp-149" for Silicon)
    format: Output format - "cif", "poscar", or "json" (default: "cif")

Returns:
    Crystal structure in the requested format

Inputs: material_id (required), format. Returns: result

search_by_band_gapB
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

Inputs: min_gap, max_gap, direct_gap_only, max_results. Returns: result

search_by_elastic_propertiesB
Search for materials by elastic/mechanical properties.

Args:
    min_bulk_modulus: Minimum bulk modulus in GPa
    max_bulk_modulus: Maximum bulk modulus in GPa
    min_shear_modulus: Minimum shear modulus in GPa
    max_shear_modulus: Maximum shear modulus in GPa
    max_results: Maximum number of results (default: 10)

Returns:
    JSON with materials matching the elastic property criteria

Inputs: min_bulk_modulus, max_bulk_modulus, min_shear_modulus, max_shear_modulus, +1 more. Returns: result

search_by_elementsB
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

Inputs: elements (required), exclude_elements, max_results. Returns: result

search_materialsB
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

Inputs: formula (required), max_results. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 10 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no significant overlap. For example, get_properties provides comprehensive details, while get_elastic_properties focuses specifically on mechanical properties, and get_structure returns crystal structure data. The search tools target different criteria (elements, band gap, elastic properties, formula), making tool selection straightforward.

    Naming Consistency5/5

    All tools follow a consistent verb_noun naming pattern using snake_case. The pattern is uniform throughout: compare_materials, get_elastic_properties, get_phase_diagram, get_properties, get_similar_structures, get_structure, search_by_band_gap, search_by_elastic_properties, search_by_elements, and search_materials. This consistency makes the tool set predictable and easy to navigate.

    Tool Count5/5

    With 10 tools, the server is well-scoped for materials science data retrieval. Each tool serves a specific function in querying and analyzing materials data, from basic searches to detailed property comparisons. The count aligns with typical MCP servers and covers the domain without being overwhelming or insufficient.

    Completeness4/5

    The tool set provides strong coverage for materials data retrieval, including search, get, and compare operations. However, there are minor gaps, such as no tools for updating or deleting data (though this may be intentional if read-only) and no specific tools for advanced analyses like thermodynamic stability or electronic structure beyond band gaps. Overall, it supports core workflows effectively.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      A tool for querying and analyzing materials data from the Materials Project database using natural language prompts, enabling materials scientists to explore properties, structures, and compositions of materials through conversational interfaces.
      3
      1
      BSD 3-Clause
    • A
      license
      Not graded
      quality
      Not graded
      maintenance
      The Materials Project MCP Server is server that provides programmatic access to the Materials Project database. It enables LLMs, to search, analyze, and retrieve up to date materials science data.
      13
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides computed (DFT) materials structures and thermodynamic properties through the Pipeworx MCP gateway, enabling AI agents to query materials data via natural language or tool calls.
      82 npm
      MIT