Materials Project MCP

A Model Context Protocol (MCP) server for querying the Materials Project database using the mp_api client.

Requirements

• Materials Project API Key - Get one here (free account required)
• Docker Desktop (must be running)
• Python 3.12+ with uv

Getting Your Materials Project API Key

1. Visit Materials Project

2. Create a free account or log in

3. Go to your dashboard

4. Navigate to API settings

5. Generate or copy your API key

6. Keep this key secure - you'll need it for setup

Installation Options

Step 1: Docker (Recommended)

Using Docker Run

1. Install Docker Desktop:

2. Pull the Docker image:

docker pull benedict2002/materials-project-mcp

3. Test the installation:

docker run --rm -i -e MP_API_KEY="your-api-key" benedict2002/materials-project-mcp

Using Docker Compose (Easiest)

1. Install Docker Desktop and make sure it's running

2. Clone the repository:

git clone 
   cd materials-project-mcp

3. Create a `.env` file:

echo "MP_API_KEY=your-materials-project-api-key" > .env

4. Test the setup:

docker-compose up

5. For background running:

docker-compose up -d

6. Stop the service:

docker-compose down

Step 1 : Local Python Installation

1. Install uv (if not already installed):

curl -Ls https://astral.sh/uv/install.sh | sh

2. Clone the repository:

git clone 
   cd materials-project-mcp

3. Create and activate virtual environment:

uv venv
   source .venv/bin/activate  # Linux/macOS
   # or
   .venv\Scripts\activate     # Windows

4. Install dependencies:

uv pip install -r requirements.txt

5. Set your API key:

export MP_API_KEY="your-api-key"  # Linux/macOS
   # or
   set MP_API_KEY=your-api-key       # Windows

6. Test the installation:

python server.py

Step 2 : Setup with Claude Desktop

1. Locate your Claude configuration file:

2. Choose your configuration method:

Using Docker Run

{
     "mcpServers": {
       "Materials Project MCP": {
         "command": "docker",
         "args": [
           "run", "--rm", "-i",
           "-e", "MP_API_KEY=your-materials-project-api-key",
           "benedict2002/materials-project-mcp"
         ]
       }
     }
   }

3. Replace `your-materials-project-api-key` with your actual API key

4. Ensure Docker Desktop is running

5. Restart Claude Desktop

6. Verify installation:

Setup with VS Code Copilot

1. Open VS Code Settings:

2. Add MCP configuration:

{
     "mcp": {
       "inputs": [],
       "servers": {
         "Materials Project MCP": {
           "command": "docker",
           "args": [
             "run", "--rm", "-i",
             "-e", "MP_API_KEY=your-api-key",
             "benedict2002/materials-project-mcp"
           ]
         }
       }
     },
     "chat.mcp.discovery.enabled": true,
     "workbench.secondarySideBar.showLabels": false
   }

3. Alternative: Local Python setup for VS Code:

{
     "mcp": {
       "inputs": [],
       "servers": {
         "Materials Project MCP": {
           "command": "/usr/local/bin/uv",
           "args": [
             "run",
             "--with",
             "mcp[cli],aiohttp,pydantic,mp_api,pymatgen,emmet-core",
             "/path/to/your/server.py"
           ],
           "env": {
             "MP_API_KEY": "your-api-key"
           }
         }
       }
     },
     "chat.mcp.discovery.enabled": true
   }

4. Replace placeholders:

5. Ensure Docker Desktop is running (for Docker configurations)

6. Restart VS Code

7. Test in VS Code:

Testing & Development (developers)

Testing Your Installation

1. Test MCP server locally:

mcp dev server.py

Look for the line "🔗 Open inspector with token pre-filled:" and use that URL

Development Workflow

1. Create a feature branch:

git checkout -b feature-name

2. Make your changes and test:

# Local testing with MCP Inspector
   mcp dev server.py
   # Use the inspector URL to test your changes interactively
   
   # Docker testing
   docker build -t materials-project-mcp-local .
   docker run --rm -i -e MP_API_KEY="your-api-key" materials-project-mcp-local
   
   # Docker Compose testing
   docker-compose up --build

3. Commit and push:

git add .
   git commit -m "Add feature description"
   git push origin feature-name

4. Open a pull request

Available Tools & Features

• search_materials - Search by elements, band gap range, stability
• get_structure_by_id - Get crystal structures and lattice parameters
• get_electronic_bandstructure - Plot electronic band structures
• get_electronic_dos_by_id - Get electronic density of states
• get_phonon_bandstructure - Plot phonon band structures
• get_phonon_dos_by_id - Get phonon density of states
• get_ion_reference_data_for_chemsys - Download aqueous ion reference data for Pourbaix diagrams
• get_cohesive_energy - Calculate cohesive energies
• get_atom_reference_data - Retrieve reference energies of isolated neutral atoms
• get_magnetic_data_by_id - Magnetic properties and ordering
• get_charge_density_by_id - Charge density data
• get_dielectric_data_by_id - Dielectric constants and properties
• get_diffraction_patterns - X-ray and neutron diffraction
• get_xRay_absorption_spectra - XAFS, XANES, EXAFS spectra
• get_elastic_constants - Mechanical properties
• get_suggested_substrates - Find substrates for thin films
• get_thermo_stability - Thermodynamic stability analysis
• get_surface_properties - Surface energies, work functions, and Wulff shapes
• get_grain_boundaries - Computed grain boundaries for a material
• get_insertion_electrodes - Insertion electrode and battery data
• get_oxidation_states - Element oxidation states, formula, and structure info

Troubleshooting

Common Issues

1. "Invalid API key" error:

2. "Docker not found" or "Cannot connect to Docker daemon":

3. Container startup issues:

4. Docker Compose issues:

5. MCP server not recognized in Claude:

Getting Help

• MCP Inspector: Use `mcp dev server.py` for interactive testing and debugging.
• GitHub Issues: Create an Issue for bug reports, feature requests, or questions.
• Materials Project API Docs: docs.materialsproject.org
• MCP Documentation: modelcontextprotocol.io
• Docker Help: docs.docker.com

Authors

• Benedict Debrah
• Peniel Fiawornu

Reference

Yin, Xiangyu. 2025. "Building an MCP Server for the Materials Project." March 23, 2025. https://xiangyu-yin.com/content/post_mp_mcp.html.