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

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

• Model Context Protocol
• MCP Python SDK
• Materials Project
• Materials Project API
• pymatgen

Author

Hesham Salama