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)

Resources (2)

Prompts (3)

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