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:

   • Download from docker.com

   • Install and make sure Docker Desktop is running

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 <repository-url> cd materials-project-mcp

3. Create a

   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 <repository-url> 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:

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

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

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

4. Ensure Docker Desktop is running

5. Restart Claude Desktop

6. Verify installation:

   • Open a new chat in Claude

   • Ask something like "Search for silicon materials in the Materials Project database" or test any of the availabe tools.

   • You should see Materials Project data in the response

Setup with VS Code Copilot

1. Open VS Code Settings:

   • Press Ctrl+Shift+P (Windows/Linux) or Cmd+Shift+P (macOS)

   • Type "Preferences: Open User Settings (JSON)"

   • Select it to open settings.json

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:

   • your-api-key with your Materials Project API key

   • /path/to/your/server.py with the actual path to server.py

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

6. Restart VS Code

7. Test in VS Code:

   • Open VS Code chat/copilot

   • Ask about materials from the Materials Project

   • The Docker container will start automatically when VS Code makes requests

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:

   • Verify your API key is correct

   • Check that you've set the environment variable properly

   • Ensure your Materials Project account is active

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

   • Make sure Docker Desktop is installed and running

   • You should see the Docker Desktop icon in your system tray/menu bar

   • Try docker --version to verify Docker is accessible

   • On Windows/Mac: Open Docker Desktop application

   • On Linux: Start Docker service with sudo systemctl start docker

3. Container startup issues:

   • Docker containers start automatically when Claude/VS Code makes requests

   • No need to manually start containers - they're ephemeral (start → run → stop)

   • Each query creates a fresh container instance

4. Docker Compose issues:

   • Make sure Docker Compose is installed: docker-compose --version

   • Check your .env file exists and has the correct API key

   • Verify the docker-compose.yml file is in the correct location

   • Ensure Docker Desktop is running

5. MCP server not recognized in Claude:

   • Check your configuration file path

   • Verify JSON syntax is correct

   • Restart Claude Desktop after configuration changes

   • Ensure Docker Desktop is running

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.